Troubleshooting

Installation & Setup

cf install fails with permission error

Symptom: EACCES or permission denied when running cf install.

Fix: Make sure you have write access to the Claude Code config directories:

# Check ownership
ls -la ~/.claude/

# Fix if needed
chmod -R u+rw ~/.claude/

If you installed the CLI globally with sudo, reinstall without it:

npm install -g coding-friend-cli

cf install says "Claude Code CLI not found"

Symptom: The installer can't detect the claude CLI binary.

Fix: Ensure Claude Code is installed and accessible in your PATH:

which claude    # Should show a path
claude --version

If claude is installed but not in PATH, restart your terminal or add its location to your shell profile.

Hooks not firing after install

Symptom: You ran cf install successfully but skills don't auto-invoke and auto-approve doesn't work.

Cause: Hooks are registered in Claude Code's settings files. If the settings file was overwritten or the hook paths are stale, they won't fire.

Fix:

1. Check that hooks are registered:

cat ~/.claude/settings.json | grep -A2 "hooks"

2. Re-run install to refresh hook paths:

cf install --user    # or --project for project-level

3. Restart Claude Code after reinstalling.

Auto-Approve

Auto-approve blocks a tool it shouldn't

Symptom: A tool call that should be safe gets blocked with a "DANGEROUS" classification.

Cause: The LLM classifier (Step 3) made an overly cautious decision.

Fix:

1. Approve the action manually when prompted — the classifier is advisory, not final.
2. If a specific command is consistently blocked, add a targeted permission rule:

cf permission
# → Browse to the relevant category and enable the rule

3. You can also inspect why a tool call was classified the way it was:

cf permission --explain '{"tool_name": "Bash", "tool_input": {"command": "your-command-here"}}'

See Auto-Approve reference for the full classification flow.

Auto-approve approves something dangerous

Symptom: A risky operation was auto-approved when it shouldn't have been.

Fix:

1. Use git to revert any unwanted changes.
2. Review your permission rules — you may have overly broad allow patterns:

cf permission    # Review and tighten rules

3. Check if you have dangerous rules like Bash(*) in your Claude Code settings. The CLI audits these when you enable auto-approve, but they can be added manually later.

Memory System

cf memory start-daemon fails

Symptom: The memory daemon won't start or crashes immediately.

Possible causes:

1. Port conflict: Another process is using the same port.

# Check if something is already running
cf memory status

2. MCP server not built: The daemon requires the MCP server to be compiled.

# If using from source, rebuild
cd <coding-friend-mcp-dir> && npm run build

3. Stale PID file: A previous daemon didn't shut down cleanly.

cf memory stop-daemon   # Clean up stale state
cf memory start-daemon  # Try again

MCP server not connecting

Symptom: Memory tools (memory_store, memory_search, etc.) are unavailable in Claude Code.

Fix:

1. Verify the MCP server is configured:

cf mcp    # Shows current MCP configuration and detects stale paths

2. Check that .mcp.json uses the version-stable format. Run cf mcp — if it warns about a stale path, update it:

cf memory mcp   # Rewrites .mcp.json with the npx format

3. Restart Claude Code — MCP servers are connected at session start.

Memory MCP path broken after CLI update

Symptom: Memory tools stop working after running cf update or switching Node.js versions. Claude Code shows an MCP connection error.

Cause: The .mcp.json in your project was written with an absolute path to the old CLI installation (e.g. /Users/you/.nvm/versions/node/v22.x.x/lib/node_modules/coding-friend-cli/...). After the CLI moves, that path no longer exists.

Fix:

cf memory mcp

This rewrites the coding-friend-memory entry in .mcp.json using the version-stable npx format, which resolves the current CLI at runtime and won't break on future updates.

You can also run cf mcp to check whether stale paths are detected before they cause issues.

Memory search returns no results

Symptom: memory_search returns empty even though you have memory files.

Fix:

1. Check that memory files exist:

ls docs/memory/

2. Rebuild the search index:

cf memory rebuild

3. If using Tier 2 (daemon), make sure the daemon is running:

cf memory status
cf memory start-daemon

Skills

Skill not auto-invoking

Symptom: You expect a skill to auto-invoke (e.g., cf-tdd before writing code) but it doesn't.

Cause: Auto-invoked skills depend on the SessionStart and PreToolUse hooks being active.

Fix:

1. Make sure Coding Friend is installed:

cf install --user

2. Check that the hook is registered in settings — look for coding-friend entries in your Claude Code hooks config.

3. Start a new Claude Code session — hooks are loaded at session start.

/cf-* command not recognized

Symptom: Typing /cf-plan or another slash command does nothing or shows "unknown command".

Cause: Skills are loaded via the plugin system, not as CLI commands. They only work inside a Claude Code session with Coding Friend installed.

Fix: Make sure you're running the command inside Claude Code (not a regular terminal) and that Coding Friend is installed for the current project or globally.

CLI

cf command not found

Symptom: cf: command not found after installation.

Fix:

# Verify installation
npm list -g coding-friend-cli

# If not installed
npm install -g coding-friend-cli

# If installed but not in PATH, check npm global bin
npm bin -g

Add the npm global bin directory to your PATH if it's not already there.

Still stuck?

If your issue isn't listed here:

1. Run cf status to see a full diagnostic of your installation
2. Check GitHub Issues for known problems
3. Open a new issue with your cf status output and steps to reproduce