RepoNav

RepoNav is a deterministic, read-only repository evidence service for local MCP clients. It exposes a single repo_nav_locate tool that turns a repository question, search terms, and optional anchors into verified evidence, follow-up candidates, coverage details, and next actions.

RepoNav prefers CodeGraph when the target repository is indexed and falls back to text search when necessary. It does not modify the target repository.

Requirements

• Node.js ^22.0.0 || ^24.0.0
• rg (ripgrep) for the text-search fallback
• Optional: CodeGraph for indexed repository exploration

Install

npm i -g repo-nav@beta

MCP host configuration

After install, register the stdio MCP server (repo-nav-mcp):

{
  "command": "repo-nav-mcp"
}

The server publishes one read-only MCP tool:

repo_nav_locate

Example arguments:

{
  "repoPath": "D:\\path\\to\\target-repository",
  "question": "Where is the repository evidence service token used?",
  "terms": ["REPOSITORY_EVIDENCE_SERVICE"],
  "anchors": [{ "kind": "symbol", "value": "REPOSITORY_EVIDENCE_SERVICE" }]
}

See the MCP getting-started guide and the repo_nav_locate reference for the full contract.

Debug CLI

The global install exposes repo-nav:

repo-nav --help
repo-nav debug locate --help
repo-nav debug probe --help

See the debug CLI guide for command details and exit-code semantics.

Programmatic API

Root package exports (repo-nav) are v2-only. Import legacy v1 contracts from repo-nav/legacy-v1.

Development from source

git clone https://github.com/gchigoo/repo-nav.git
cd repo-nav
npm ci
npm run build

Register a local stdio server with Codex:

codex mcp add repo_nav -- node <ABSOLUTE_REPO_PATH>\dist\main.js
codex mcp list

Golden regressions run from a source checkout via npm run test:golden only.

Verification

npm run build && npm run typecheck && npm test
npm run test:golden -- --all
npm run test:mcp -- --all
npm run test:docs

The MVP acceptance contract and evidence are documented in docs/acceptance/mvp.md.

Design principles

• Read-only repository access
• Deterministic and typed output contracts
• Explicit distinction between confirmed evidence and candidates
• Bounded results with coverage and next-action metadata
• Secret-like value redaction at public output boundaries
• CodeGraph-first retrieval with a controlled fallback path