Troubleshooting & FAQ

If something is not working, start here. Most issues are resolved by running:

planu doctor

This command checks your installation, config files, and AI tool connections, then tells you exactly what to fix.

---

Installation Issues

MCP not detected after install

Your AI tool needs to be fully restarted — not just the window, but the entire process.

Claude Code:

# Quit Claude Code completely, then reopen it
# Verify Planu is listed:
claude mcp list

Cursor / Windsurf / Zed: Close the application from the taskbar/dock (not just the window), then reopen.

Still not detected?

Run planu doctor — it will show which config files were written and whether the AI tool can see them.

---

Wrong config file path

Planu writes config to different locations depending on your OS and scope (user vs project).

Scope	Claude Code	Cursor	Windsurf
User (macOS/Linux)	~/.claude/claude.json	~/.cursor/mcp.json	~/.codeium/windsurf/mcp_config.json
User (Windows/WSL)	%APPDATA%\Claude\claude.json	%APPDATA%\Cursor\mcp.json	%APPDATA%\Windsurf\mcp_config.json
Project	.claude/claude.json	.cursor/mcp.json	.windsurf/mcp_config.json

How to check which config file is active

planu doctor

The output includes a Config files section showing the exact paths that were written and whether the AI tool can read them.

For Claude Code specifically:

claude mcp list
# Expected output includes:
# planu — planu serve

---

Permissions errors running npx

Fix npm permissions on macOS/Linux

This happens when npm's global directory is owned by root. Fix it without sudo:

# Option 1: Use a user-owned prefix
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc

# Option 2: Use nvm (recommended for developers)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Then reinstall Node.js via nvm

After fixing, verify:

planu install --global

Never use sudo with npm

Running sudo npm install -g masks permission problems and creates files owned by root, which causes more errors later. Fix the underlying permissions instead.

---

"command not found: planu" after npm install -g

The global npm bin directory is not in your PATH.

# Find where npm installs global binaries:
npm config get prefix
# Typical output: /usr/local  →  binaries are in /usr/local/bin

# Add to PATH if missing (macOS/Linux):
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify:
planu --version

Prefer npx over global install

You can always use planu <command> without installing globally. The installer uses npx internally, so global install is optional.

---

AI Tool Connectivity

Claude Code not showing Planu tools

1. Run planu doctor to verify the config was written correctly
2. Run claude mcp list — Planu must appear in the output
3. Start a new conversation and type: list my planu tools
4. If Claude Code asks for permission, approve it (or auto-approve — see Getting Started)

claude mcp list
# Expected:
# planu    planu serve    [active]

MCP tools are per-conversation

Tools load when a conversation starts. If you installed Planu while a conversation was open, start a new one.

---

Cursor / Windsurf not picking up the MCP after install

Manually verify the config file

Cursor — check ~/.cursor/mcp.json:

{
  "mcpServers": {
    "planu": {
      "command": "planu",
      "args": ["serve"]
    }
  }
}

Windsurf — check ~/.codeium/windsurf/mcp_config.json (same structure).

If the file is correct but the tool still does not appear:

1. Close the application completely
2. Reopen it
3. Wait ~10 seconds for the MCP server to start
4. Open a new chat and type a Planu command

---

"Tool not found" error in Claude

This means Claude is not connected to the Planu MCP server in the current conversation.

# Re-verify installation:
planu doctor

# Re-add if needed:
claude mcp add planu -- npx -y @planu/cli@latest

Then start a new conversation — MCP connections are established at conversation start.

---

How to verify installation

planu doctor

Expected output:

Planu Doctor v0.89.0
====================
Node.js:     24.x     OK
npx:         10.x     OK
Config:
  Claude Code  ~/.claude/claude.json     found
  Cursor       ~/.cursor/mcp.json        found
License:     Pro — user@email.com
Status:      All checks passed

---

Spec Workflow Issues

validate always fails even after implementing

The validate tool checks whether your code matches the acceptance criteria in the spec. A few common reasons it fails:

1. The criteria are too vague — run check_readiness to improve them before implementing
2. Wrong project path — make sure you pass the correct source directory
3. Spec and code are genuinely misaligned — check which criteria are failing and implement the missing pieces

Prompt: "Validate spec SPEC-003 against the code at /path/to/src"

What to do when validate keeps failing

Prompt: "Show me which criteria are failing for spec SPEC-003"

This lists each criterion with its coverage status. Focus on the uncovered ones. If a criterion is met but still failing, it may be worded in a way the validator cannot detect — use reconcile_spec to update the wording to match the actual implementation.

---

Drift detected incorrectly (false positive)

detect_drift compares your current code to what the spec describes. False positives happen when:

• The spec was written with very specific implementation details that changed (but the behavior is the same)
• You refactored code without updating the spec

If the drift is intentional (the spec needs updating to match the real implementation):

Prompt: "Reconcile spec SPEC-003 with the implementation changes in project [id]"

reconcile_spec walks you through each change and asks for per-change approval before updating the spec.

Drift is not always bad

Drift means "the plan and the code disagree." Sometimes the code is right and the plan is outdated — that is when you reconcile. Sometimes the code is wrong — that is when you fix the code.

---

Spec not found by tools

Tools identify specs by ID (e.g., SPEC-003) within a project. If a spec is not found:

# Check the project ID for the current directory:
planu status

# List all specs in the project:
# Prompt: "List all specs in project [id]"

Common causes:

• Using the wrong project ID (Planu uses a hash of the project path)
• The spec was created in a different directory than the one you are currently in

---

create_spec times out on large projects

On very large projects (millions of files), the initial scan can take longer than expected.

Limit the scan scope:

Prompt: "Create a spec for [feature] in project [id], scan only the src/ directory"

You can also pre-run the scan once to cache results:

Prompt: "Scan project [id] at path /path/to/project, limit to src/"

Subsequent create_spec calls on the same project will use the cached scan.

---

Performance

Slow first response (cold start)

The first response in a new conversation is slower because:

1. npx downloads the latest version of @planu/cli (a few seconds)
2. The MCP server initializes and loads your project's data

This is a one-time cost per conversation. Subsequent tool calls are fast.

Reduce cold start time

Use --prefer-online (already included in the default config) to cache the package locally. After the first run, npx reuses the cached version and only checks for updates.

---

Large project scan taking too long

Prompt: "Scan project [id] at /path/to/project, limit scan to src/ and tests/"

You can also exclude directories by listing them:

Prompt: "Scan project [id], exclude node_modules, dist, .git, and vendor directories"

---

How to limit scan scope

Pass explicit path restrictions when creating specs or scanning:

Prompt: "Create a spec for payment processing, scanning only src/payments/ in project [id]"

Planu respects these boundaries and will not analyze files outside the specified path.

---

Getting Help

If none of the above solved your issue, gather diagnostic information first:

planu doctor

Copy the full output and include it in your bug report.

What to include in a bug report

• Full output of planu doctor
• The command or prompt that triggered the issue
• The exact error message or unexpected behavior
• Your OS and Node.js version: node --version
• Your AI tool and version (e.g., Claude Code 1.x, Cursor 0.4x)

Report an issue

Ask your installed Planu agent to submit_feedback with the planu doctor output and a description of what you expected versus what happened. If Planu cannot start, use the public Discord support channel.

Community support

Search existing issues before opening a new one — your problem may already have a solution or a workaround.