MCP Client Setup
Register codemap-search mcp in your client, then start the client inside the target repository.
Register with a client
Section titled “Register with a client”Register across projects for your user account:
claude mcp add --scope user codemap-search -- codemap-search mcpOr write a shared .mcp.json entry inside the target repository:
claude mcp add --scope project codemap-search -- codemap-search mcpOmitting --scope saves a private local entry for the current repository in ~/.claude.json.
codex mcp add codemap-search -- codemap-search mcpOr add to ~/.codex/config.toml:
[mcp_servers.codemap-search]command = "codemap-search"args = ["mcp"]-
Install @buyong/pi-mcp-adapter:
Terminal window pi install npm:@buyong/pi-mcp-adapter -
Disable built-in MCP by adding
"-builtin:mcp"toextensionsin~/.pi/agent/settings.json(or turn offmcpunder Built-in inpi config). -
Add the server to
~/.pi/agent/mcp.jsonor.pi/mcp.json:{"mcpServers": {"codemap-search": { "command": "codemap-search", "args": ["mcp"] }}} -
If
piis already running, run/reload.
Add to ~/.config/opencode/opencode.json or a repository opencode.json:
{ "$schema": "https://opencode.ai/config.json", "mcp": { "codemap-search": { "type": "local", "command": ["codemap-search", "mcp"], "enabled": true } }}Verify
Section titled “Verify”- Open a new session in the target repository and ask the agent to call
initial_instructionsorfindto confirm the repository path. - If indexing is warming up on first launch, wait for it to finish and ask the agent to run
searchon a known symbol.
- Binary not found: Check terminal
PATHin Installation Troubleshooting. For GUI clients that do not load~/.zshrcor~/.bashrc, setcommandto the full path fromwhich codemap-search(where.exe codemap-searchon Windows). - Wrong directory indexed: Start the client inside the target repository (
codemap-searchrefuses to run in~).
Global instructions (optional)
Section titled “Global instructions (optional)”To automatically add a one-line codemap-search navigation reminder to your client’s global instructions file (CLAUDE.md or AGENTS.md), add this to ~/.codemap/config.toml and start a new session:
[global_instructions]enabled = trueSee Global instructions for per-client file paths.