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.

The repository now contains the 2.0.0 candidate implementation: canonical v2 execution facts are the production authority, snapshot revalidation uses the selected conditional-digest policy, and the legacy package subpath is removed. Publishing and release tagging remain owner-controlled actions. See the current project status.

Requirements

• Node.js ^22.0.0 || ^24.0.0

• rg (ripgrep) for the text-search fallback

• Optional: CodeGraph for indexed repository exploration

Related MCP server: Semantic Search MCP Server

Install

npm i -g repo-nav@2.0.0

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. terms drive the search; question is display-only and does not change the plan. MCP text content is a compact agent view; structuredContent stays the full schema 2.0 result.

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) expose the v2 request/result contract and application helpers. The current public export map is:

The root still re-exports the approved deprecated adapter symbols; new code should import them from the dedicated subpaths. repo-nav/advanced is public but is not the preferred high-level API. repo-nav/legacy-v1 is no longer exported in 2.0.0. Deep imports outside the export map are unsupported.

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 run lint
npm run format:check
npm test
npm run test:golden -- --all
npm run test:mcp:built -- --all
npm run test:docs:built
npm run test:platform
node tools/release/check-legacy-subpath-absence.mjs --workspace .

npm run test:integration:codegraph is a separate live integration surface and requires CodeGraph 1.5.0 on PATH. Package and release-oriented checks are listed in docs/acceptance/mvp.md. The current CI matrix and remaining hardening work are summarized in docs/project-status.md.

npm run benchmark:codegraph-differential compares the pinned CodeGraph CLI's exact-symbol top-K directly with repo-nav's CodeGraph-first composition. Every standalone location must remain in the same prefix position, stay confirmed, and retain CodeGraph provenance; fallback noise, demotion, loss, redacted locators, a version mismatch, or an unexecuted case fails the command. The broader local quality gate may skip unindexed fixtures, while CI prepares both indexes and sets REPO_NAV_REQUIRE_CODEGRAPH_DIFFERENTIAL=1 so it also fails closed.

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