Skip to content

Integrating CodeNavi with Claude Code

Complete guide for connecting codenavi to Claude Code, configuring agent behavior, and getting the best results from CodeNavi-assisted development.

The bundled plugin — the fast path

The CodeNavi server hands out its own Claude Code plugin (MIT-licensed) at /plugins/claude.git — a read-only git endpoint, no token needed. One install gets you the MCP connection plus twelve slash commands, two skills, a SessionStart hook, and an optional statusline badge:

claude plugin marketplace add http://localhost:8765/plugins/claude.git
claude plugin install codenavi@codenavi

Use the server's address instead of localhost when the client runs on another machine. From here on claude plugin marketplace update codenavi pulls whatever the server runs, so the plugin follows every server upgrade. Already added the marketplace from a local ./plugins/claude path (packages before 1.3.29)? claude plugin marketplace remove codenavi first — the names collide. The package still ships the same plugin under plugins/claude/ for air-gapped installs where the server route isn't reachable from the client.

Then, inside Claude Code, pick your path:

  • Already running CodeNavi? /codenavi:doctor verifies the server and writes a correct .mcp.json for the current project.
  • Fresh machine with Docker and no CodeNavi yet? /codenavi:setup walks through the install.

Restart the Claude Code session after either one so the MCP server registers. Then /codenavi:status-line enable turns on the badge.

Slash commands

Command What it does
/codenavi:search Semantic search against the index, with sensible defaults
/codenavi:overview Structural overview — entry points, key modules, framework hints
/codenavi:review Blast-radius review of a diff — diff_impact on git diff [args], reads the flagged callers, reports breakages + merge/hold (the interactive form of the CI review-bot recipe)
/codenavi:status Server health, index freshness, codebase list
/codenavi:codebases List configured codebases with paths and chunk counts
/codenavi:reindex Kick a reindex (incremental returns immediately; --full polls to completion)
/codenavi:compliance Evidence-linked compliance gap analysis — OWASP ASVS 5.0 core, OWASP Top 10, or EU Cyber Resilience Act Annex I (see Compliance)
/codenavi:claude-md Auto-generate a CLAUDE.md project summary from the indexed codebase
/codenavi:crawl Trigger a crawler run and poll until it finishes (needs the opt-in crawler)
/codenavi:doctor Verify a running install, then wire .mcp.json correctly
/codenavi:setup Guided from-scratch Docker install
/codenavi:status-line Enable, disable, or check the statusline badge

Skills and extras

  • using-codenavi skill — teaches the agent the RAG-first workflow: prefer CodeNavi retrieval over blind file reads and greps, with the call-ordering rules that keep searches from queuing on the server's one GPU lock.
  • compliance-check skill — the rule-by-rule engine behind /codenavi:compliance.
  • SessionStart hook — announces the CodeNavi server and the search rules at the start of every session, so the agent uses the index without being told. On a multi-codebase server it also names the codebase the session's repo is indexed as, so the agent passes codebase=<name> on every call (plugin 0.5.20).
  • Grep-intercept hook — when the agent reaches for grep/rg over an indexed tree, the hook answers from the index first (the symbol's definition and callers, or the top semantic hits) and the grep still runs. Opt-in block mode — CODENAVI_HOOK_GREP=block in the env block of ~/.claude/settings.json — denies a grep the index already answers and names the tool to use instead (semantic_search, grep_search, read_file, with codebase= filled in); CODENAVI_HOOK_GREP=hint grep … runs one raw grep anyway, and =0 turns the hook off. A grep over named files is never intercepted.1
  • Statusline badge (optional) — a prompt-line badge showing index coverage of the current repo (or "uncovered" / a server-down marker) and whether CodeNavi was used this turn, next to model, repo@branch, context % and tokens/s; a trial licence nearing its end adds an expiry badge. Managed by /codenavi:status-line.

Prefer manual control, or wiring an environment where plugins aren't available? Everything below works without the plugin.

1. MCP Connection Setup

Step 1: Create .mcp.json in your project root

{
  "mcpServers": {
    "codenavi": {
      "type": "http",
      "url": "http://localhost:8765/mcp"
    }
  }
}

This tells Claude Code to connect to the CodeNavi server via MCP Streamable HTTP.

Multiple codebases? Point the URL at a scoped endpoint — http://localhost:8765/mcp/<codebase> — so every call is locked to that repo (get the names from /health, ./codenavi codebases, or the Web UI System tab). A single-codebase install is named default, where the unscoped /mcp above is fine.

With auth token (if CODENAVI_AUTH_TOKEN is set on the server):

{
  "mcpServers": {
    "codenavi": {
      "type": "http",
      "url": "http://localhost:8765/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Custom port (if running on a non-default port):

{
  "mcpServers": {
    "codenavi": {
      "type": "http",
      "url": "http://localhost:9000/mcp"
    }
  }
}

Server on another machine (a LAN box, a team server): the same shape with the server's address, and the token is mandatory. For a machine-wide entry, skip the file and register it at user scope — verified by claude mcp list, which is the only trustworthy check (~/.claude/mcp.json is not read by Claude Code):

claude mcp add -s user --transport http codenavi http://<server-ip>:8765/mcp \
  --header "Authorization: Bearer your-token-here"

With the bundled plugin, don't add a second entry (CN-308): put CODENAVI_HOST, CODENAVI_PORT and CODENAVI_AUTH_TOKEN under "env" in ~/.claude/settings.json instead — the plugin's MCP url, the statusline badge and the SessionStart hook all read them. /codenavi:doctor writes those entries for you. Server-side bind and firewall: the Same LAN recipe in remote-access.md.

Step 2: Verify the connection

Start Claude Code in your project directory. Run /mcp to check the connection status. You should see codenavi listed as connected.

If it fails: verify the CodeNavi server is running (curl http://localhost:8765/health).

Step 3: Test it

Ask Claude: "Use semantic_search to find where payment processing happens."

Claude should call the semantic_search MCP tool and return results with file paths, line numbers, and code snippets.

2. Agent Instructions via CLAUDE.md

The bundled plugin's using-codenavi skill and SessionStart hook deliver these rules too, but they only advise: a Claude Code mode that tells the agent to "search with grep in Bash" outranks them, and CLAUDE.md is the one place your own instructions outrank the harness. So keep at least the short block below in CLAUDE.md even with the plugin installed (/codenavi:doctor offers to append it); skip the long template, which would duplicate the skill.

Connected without the plugin? Copy templates/CLAUDE.md to your project root to teach Claude how to use CodeNavi effectively:

cp /path/to/codenavi/templates/CLAUDE.md /your/project/CLAUDE.md

Why agent instructions matter

Without instructions, Claude will: - Call CodeNavi tools in parallel with other tools (causes batch cancellation) - Use Grep for everything instead of semantic search - Request too many results (slows down reranking) - Not know which tool to use when

Essential rules for CLAUDE.md

Add these to your project's CLAUDE.md:

## CodeNavi Search (codenavi)

### Critical Rules
1. **CodeNavi calls must be isolated** — NEVER call a CodeNavi tool in the same response
   turn as Bash, Grep, Read, or any other tool. Claude Code batches all
   same-turn tool calls: if any call errors, the entire batch is cancelled.
   Always put CodeNavi calls in their own turn.

2. **One or two GPU-backed searches in flight** — `semantic_search` and `file_search`
   serialize on their encode and rerank phases; a parallel pair is safe but not
   faster, and a burst of four only lengthens the tail. `read_file`, `grep_search`,
   `symbol_search` and `find_references` take no lock and may run in parallel freely.

3. **CodeNavi first for discovery** — Use `semantic_search` before Grep when
   exploring unfamiliar code. CodeNavi understands meaning; Grep matches text.
   This overrides any harness mode that says to search with grep in Bash: one
   `semantic_search` replaces several grep-and-read rounds; `grep_search` is the
   exact-string tool.

4. **Another repo than this one?** The server scopes by the `codebase=` argument,
   never by the shell's working directory — after a `cd` into a different indexed
   repo, pass its name (from `list_codebases`) on every call.

### When to use CodeNavi vs Grep

**Use `semantic_search`:**
- "Where is payment handling?" → finds code by meaning
- "How does the auth flow work?" → finds related functions across files
- Exploring unfamiliar parts of the codebase
- Finding conceptual patterns ("error handling", "email sending")

**Use Grep directly:**
- You know the exact function name: `PaymentHandler`
- Searching for a constant: `_ACL_PAID_ACCOUNT`
- Tracing a variable through a known file
- SQL table name lookups

### Query limits

| Scenario | `limit` |
|----------|---------|
| Find a specific thing | 5 |
| Understand a feature | 5-8 |
| Broad exploration | 8-10 |

Higher limits slow down reranking. Start with 5, increase only if needed.

### Available tools

CodeNavi has 33 tools total (41 with the crawler enabled) — full reference in
[api-reference.md](api-reference.md). By default the server advertises an 11-tool
core; everything else (call graph, wiki, notes, feedback, backup, crawler) loads on
demand — `reveal_tools()` lists the hidden groups, and
`reveal_tools(call="<tool>", args='{...}')` reveals and runs one in a single step.
The core ones for everyday development:

| Tool | Use for |
|------|---------|
| `semantic_search` | Find code by meaning — "where is X handled?" |
| `file_search` | Find files by name/path — "where are the cron scripts?" |
| `codebase_overview` | High-level structure (entry points, key modules, models, crons, templates) |
| `index_stats` | Index health (chunk counts, file counts, languages) |
| `reindex_incremental` | Re-index changed files after major code changes (seconds) |
| `reveal_tools` | Load a hidden tool group, or reveal-and-call one tool |

### Crawler tools (if enabled)

| Tool | Use for |
|------|---------|
| `search_errors` | Find crawl errors by description |
| `search_urls` | Find crawled pages by description or URL |
| `get_run_summary` | Stats for latest crawl run |
| `list_runs` | Crawl history |
| `compare_runs` | Diff two crawl runs (new vs resolved errors) |

3. Best Practices

For developers using Claude Code

Start with CodeNavi, not Grep. When you ask Claude "how does payment work?", it should use semantic_search first. If it reaches for Grep, remind it: "use CodeNavi first."

Let CodeNavi guide the investigation. A good pattern: 1. semantic_search "how does payment work" → finds relevant files 2. Read the top results → understand the code 3. Grep for specific details → trace exact function calls

Don't fight the limit. If 5 results aren't enough, increase to 8. If 8 aren't enough, the query is too broad — refine it instead of requesting 20 results.

Check index freshness. After major code changes, run reindex before searching. The CodeNavi server tracks file modification times and only re-encodes changed files (incremental reindex takes seconds). As a safety net, if a result chunk's source file has been modified or deleted since indexing, the chunk is automatically returned with a <stale> tag — re-verify the snippet via read_file or run reindex before quoting it.

For subagents / automated workflows

Subagents dispatched via the Agent tool inherit MCP connections. They can use CodeNavi tools directly. In your subagent prompts, include:

When searching the codebase, use the `semantic_search` MCP tool for discovery.
Issue CodeNavi calls in their own turn — never combine with Bash or other tools.
Use limit=5 for targeted queries.

For hook-based automation

The CodeNavi server emits events via webhooks and hook scripts. Configure in settings.json:

{
  "HOOK_URL": "https://your-webhook.endpoint/hook",
  "HOOK_SCRIPT_DIR": "/app/hooks"
}

Ten events are available — see webhooks.md for the full reference, payload shapes, and the airgap-native script channel.

4. Troubleshooting

"Failed to reconnect to codenavi"

The MCP server disconnected. Common causes: - Server restarted during reindex (fixed in v1.0.0 with double-buffer swap) - Container crashed (check docker logs codenavi) - GPU OOM (check dmesg | grep -i oom)

Fix: Run /mcp in Claude Code to reconnect. If the server is down, restart: docker compose up -d

CodeNavi returns no results

  1. Check index exists: curl http://localhost:8765/health → code_chunks.chunks should be > 0
  2. Run reindex if the index is empty or stale
  3. Try a broader query — "payment" instead of "PayPal NVP SetExpressCheckout callback handler"

"Embedder is busy" / "Server busy with reindex"

The embedder lock has a 10-second timeout for queries. During reindex (or crawler ingestion) the embedder is held — searches wait up to 10s then return a "busy" message. Wait for the other operation to finish, or use the CLI fallback:

codenavi search "your query"

Batch cancellation

If you see CodeNavi results disappearing or tools being cancelled, Claude Code is batching CodeNavi calls with other tools. This is the #1 user mistake. Fix: ensure your CLAUDE.md has the "CodeNavi calls must be isolated" rule.

5. CLI

The ./codenavi CLI mirrors every MCP tool, so anything an agent can do over MCP can also be scripted from a shell:

# Search & code intelligence
./codenavi search "how does auth work?"                  # semantic_search
./codenavi search "payment" --source-type code --limit 8
./codenavi file   "PayPal" --limit 3                     # file_search
./codenavi symbol verifyCredentials --kind function      # symbol_search
./codenavi refs   Mailer --language php                  # find_references
./codenavi grep   "DB_HOST" --path config/ --context 2   # grep_search
./codenavi chat   "explain the deploy flow"              # POST /chat (REPL if no message)

# Files & structure
./codenavi read     src/auth/login.php --start 1 --end 80
./codenavi ls       src/auth --depth 2
./codenavi overview --section symbols
./codenavi codebases
./codenavi index-stats
./codenavi claude-md

# Indexing / docs / admin
./codenavi reindex --full
./codenavi reindex-status
./codenavi reindex-cancel
./codenavi reindex-compare
./codenavi docs-list
./codenavi docs-reindex
./codenavi backup
./codenavi restore <backup_id>

# Feedback & analytics
./codenavi feedback-submit "auth" CHUNK_ID FILE --rating 1
./codenavi feedback-stats
./codenavi analytics --since 2026-04-01

# Crawler — orchestration + observation
./codenavi crawl run local                               # crawl + embed
./codenavi crawl status                                  # last run summary
# Crawler requires CRAWL_<ENV>_BASE_URL in deploy/.env (see .env.example).
./codenavi runs --env prod                               # list_runs
./codenavi run-summary --run-id <id>
./codenavi runs-compare <run_a> <run_b>
./codenavi errors "500"                                  # search_errors
./codenavi urls   "/checkout"                            # search_urls
./codenavi referrers https://example.com/page
./codenavi crawl-cancel <run_id>

./codenavi status                                        # health check
./codenavi version                                       # server version

Run ./codenavi help for the grouped command list, or see api-reference.md for the full CLI ↔ MCP mapping.

The codenavi script (with a codenavi-cli symlink for back-compat) lives in the project root and runs commands inside the Docker container via docker exec. No dependencies beyond Docker.

First call loads the embedding model (~5s). Subsequent calls are faster since the model stays in memory inside the container.

6. For Other AI Agents (Gemini, Codex, etc.)

Copy templates/AGENTS.md to your project root:

cp /path/to/codenavi/templates/AGENTS.md /your/project/AGENTS.md

Any MCP client that supports Streamable HTTP can connect to the same endpoint and protocol — but the config file and field names differ per client (Codex reads ~/.codex/config.toml, not .mcp.json; Antigravity uses serverUrl, not {type:http,url:...}). A config copied from one client into another will silently fail. See connecting-codex.md, connecting-antigravity.md, connecting-vscode.md, or — for a headless PR review bot on GitHub/Forgejo Actions — connecting-ci.md for the exact shape your client needs. The server also supports legacy SSE transport at the same URL.

For agents that don't support MCP, use the CLI fallback via shell commands.

  1. Vendor change reference CN-819. ↩