Codebase Research

Questions about your own code go to the navigator-research agent: a subagent with its own context window that explores, samples, and returns a summary of under 2,000 tokens. The point is not that it reads faster. The point is that it reads somewhere else — the files it opens never enter your session, only the conclusion does.

That is context engineering applied to exploration. For questions about the outside world — literature, vendors, standards — use nav-deep-research instead.

How it explores

The agent never reads a directory front to back. It works in phases, and each one is designed to answer the question without loading the codebase into memory:

1. Navigator first. Check the docs index and the knowledge graph. Many questions are already answered by a linked doc or a prior memory, in seconds and without a single search.
2. Ideal final result. Two cheap questions before any code is opened: what would have to be true for this to need no new code, and what already does 80% of it?
3. Entry points. Detect the language from its manifest, find the entry points.
4. Symbol navigation, when a language server is available. See below.
5. Patterns. Grep for the shape, then sample two or three representative files — the newest, the most imported, one entry point and one leaf.
6. Summary. Findings with path:line references, explicit unknowns, and a count of files matched versus files actually read.

The last part matters: research that hides its gaps creates false confidence. The agent is required to say what it could not determine.

Code intelligence (v7.5.0)

Claude Code exposes an LSP tool whenever a language-server plugin is installed. When that tool is present, the research agent uses it for symbol questions instead of text search:

The difference is precision. A grep for a function name also returns comments, strings, and unrelated functions that happen to share it; a language server returns the call sites and nothing else. Measured on Navigator’s own repository, a “who calls this?” question went from 9 requests and 284k context tokens to 5 requests and 142k, with a more complete answer.

There is no setting. The plugin’s presence is the toggle. Install one for your stack and the agent uses it; install nothing and it greps exactly as before. Nothing is bundled, and no language server is ever required.

/plugin install pyright-lsp@claude-plugins-official   # or typescript-lsp, gopls-lsp, rust-analyzer-lsp, …
npm install -g pyright                                 # the server binary must be on your PATH

What a language server cannot see

A language server follows static imports. It does not follow a module loaded by path at runtime, a registry keyed by string, or a call site living inside a string literal — all of which are common in plugin and hook code. The agent knows this: it confirms with grep and reports which call sites came from which tool, so a short reference list is never mistaken for a complete one.

Two more limits worth knowing. The server indexes your workspace on its first request, so a cold first answer can be incomplete; the agent retries once and takes the second answer. And outlines carry names and line numbers, not signatures — for a file under about 500 lines, one read is cheaper than an outline followed by a read anyway.

Language servers are unavailable in cloud sessions, where the phase becomes a no-op.

When to use which

Agents explore; skills execute. Exploration benefits from a separate context window because the reading is disposable. Execution benefits from a shared one because the work is not.