Troubleshooting

Project not initializing

FileScopeMCP auto-initializes to the current working directory when Claude Code starts. For a different directory, call set_base_directory(path: "/your/project"). For Cursor AI or daemon mode, pass --base-dir=/your/project as a startup argument.

MCP server not appearing in Claude Code

1. Run claude mcp list to check registration
2. If missing, run npm run register-mcp
3. Check ~/.claude.json — it should have a FileScopeMCP entry under mcpServers
4. Restart Claude Code after registration
5. If working inside the FileScopeMCP repo itself, the committed .mcp.json (repo scope) can coexist with the user-scope entry created by build.sh. The repo-scope entry uses a relative path (dist/mcp-server.js) and only resolves when Claude Code's CWD is the repo root; if the subprocess is spawned elsewhere the server fails silently. Use claude mcp list to see what is active, and claude mcp remove --scope user FileScopeMCP (or --scope project) to disambiguate if both are registered.

npm install fails on native modules

better-sqlite3 and tree-sitter include native addons. If prebuilt binaries aren't available:

• Linux: sudo apt install build-essential python3
• macOS: xcode-select --install
• Windows: Install Visual Studio Build Tools with C++ workload

LLM broker not generating metadata

1. Call status() — check broker.brokerConnected
2. Check ~/.filescope/broker.log for connection errors
3. If llama-server is running locally: curl http://localhost:8880/v1/models
4. Check ~/.filescope/broker.json — baseURL and model must be correct
5. Run ./setup-llm.sh --status to verify llama-server reachability

For the WSL2 + Windows alternative setup, see the troubleshooting section in llm-setup.md.

Stale PID file ("daemon already running" error)

cat /path/to/project/.filescope/instance.pid
kill -0 <PID> 2>/dev/null && echo "Running" || echo "Stale"

# If stale:
rm /path/to/project/.filescope/instance.pid

Database corruption

rm /path/to/project/.filescope/data.db
rm -f /path/to/project/.filescope/data.db-wal
rm -f /path/to/project/.filescope/data.db-shm

The database is rebuilt from scratch on next startup.

Log file locations

File	When active	Location
~/.filescope/broker.log	Always (broker process)	Global directory
.filescope-daemon.log	Daemon mode	Project root
.filescope/mcp-server.log	MCP server mode	Global directory (~/.filescope/)