Code Nav

AI-native deterministic code navigation MCP server for Codex / CodeCLI.

code_nav gives coding agents compact, structured repo context without making them dump files into chat. It works in any git repo by detecting the repo root and using git-visible files.

There is no semantic search, no embeddings, no vector database, no graph index, no Qdrant, no CocoIndex, and no Zoekt.

Repository:

https://github.com/ARQAWA/code-nav-mcp

Install Prompt

Use INSTALL_AGENT_PROMPT.md with Codex / CodeCLI on the target machine.

The prompt installs one shared user-level code_nav MCP:

$HOME/.local/share/code-nav-mcp/app
$HOME/.local/bin/code-nav-mcp

It also installs/checks Probe, ast-grep, ripgrep, and RTK, configures Codex MCP globally, installs Code Navigation Rules, and verifies the MCP tools.

Tools

Tool	Purpose
code_nav.health	Check repo detection and dependency health.
code_nav.search	Main deterministic code discovery workflow.
code_nav.find_file	File/path discovery.
code_nav.exact_search	Ranked exact text search, not proof.
code_nav.extract_context	Compact code context extraction.
code_nav.structural_search	AST search with ast-grep.
code_nav.exact_audit	Exhaustive proof using raw rg/git grep.
code_nav.coverage	File coverage and no-semantic-index status.

Local Development

npm install
npm run build
npm test
npm run doctor
npm run self-test

Run the MCP server locally:

node dist/cli.js mcp

Optional Repo Config

No per-repo config is required. Rare overrides can use .code-navrc.json:

{
  "max_file_bytes": 2097152,
  "extra_exclude": [],
  "extra_include": [],
  "markdown": "normal",
  "result_limit": 12
}