codebase-index

Give AI coding agents a precise map of your codebase — locally, privately, and with evidence.

Find implementations. Trace behavior. Predict change impact.

Quick start · Install · Benchmarks · Security · MCP

The short version

codebase-index is a local retrieval and code-graph layer for Claude Code, Codex CLI, OpenCode, and MCP clients. It indexes a repository into SQLite, extracts symbols and relationships with Tree-sitter, and gives agents ranked file:line evidence instead of making them scan broad sets of files.

Question → ranked retrieval → dependency evidence → precise answer

It is not an IDE and not another coding agent. Your existing agent remains the interface; codebase-index gives it better aim.

Find. Trace. Predict.

Every retrieval packet carries:

• ranked matches and the reason each match scored;
• exact line ranges to read next;
• index freshness;
• answer confidence and targeted fallbacks;
• graph coverage and edge confidence where relevant.

That evidence contract lets an agent distinguish “nothing references this” from “the graph is partial, so verify with a targeted search.”

Install in five minutes

pip install codebase-index
cd your-project
codebase-index init
codebase-index index
codebase-index search "where is authentication implemented?"

init can install resources for Claude Code, Codex CLI, OpenCode, and detected MCP clients:

codebase-index init --target auto
codebase-index init --target codex
codebase-index init --target claude
codebase-index init --target opencode

pipx install codebase-index is supported as an isolated alternative. See the installation guide for pinned releases, editable installs, hooks, Windows details, and troubleshooting.

Claude Code plugin

/plugin marketplace add denfry/codebase-index
/plugin install codebase-index@codebase-index

The plugin provisions a private environment on first use. Later sessions run offline, and the first codebase question builds the index automatically.

What the agent receives

{
  "query": "where is authentication implemented?",
  "confidence": "high",
  "results": [
    {
      "path": "src/auth/AuthService.ts",
      "line_start": 12,
      "line_end": 148,
      "score": 0.92,
      "reason": "exact symbol match, 4 callers"
    }
  ],
  "recommended_reads": [
    {
      "path": "src/auth/AuthService.ts",
      "line_start": 12,
      "line_end": 148
    }
  ],
  "index": {
    "exists": true,
    "stale": false
  }
}

Snippets are skeletonized when that preserves evidence while saving tokens. Unrelated bodies collapse, but imports, signatures, matched lines, and exact read ranges remain.

Core commands

# Find
codebase-index search "auth token refresh"
codebase-index symbol AuthService

# Trace
codebase-index explain "authentication flow"
codebase-index refs send_email
codebase-index path ApiController Database
codebase-index describe Database
codebase-index architecture

# Predict
codebase-index impact User --direction up --depth 2
codebase-index diff-impact --base HEAD --direction up --depth 2

# Inspect and visualize
codebase-index graph User --direction both --depth 2 --output graph.html
codebase-index stats
codebase-index doctor

Add --json for agents and automation. Search supports hybrid, fts, symbol, and opt-in vector modes.

Why not just grep?

Grep is excellent when you know the exact text. Repository questions often need more:

Use grep for one known string. Use codebase-index when the agent must locate, understand, or assess a change across a repository.

The comparison guide also covers Cursor, Aider repo-map, Sourcegraph, Continue, Amp, and Codebase-Memory MCP—including when those tools are the better choice.

Measured results

On the published 55k LOC Java benchmark:

• Recall@3: 70% for codebase-index versus 40% for the rg baseline;
• answer-context tokens: approximately 13× fewer;
• raw results and methodology are checked into the repository.

These results are evidence for that benchmark, not a claim of universal superiority. Large public-repository and framework-graph evaluations remain on the roadmap. Read the complete methodology and limitations in BENCHMARKS.md.

Local by default

The base install:

• makes no network requests;
• sends no telemetry;
• stores the derived index inside the project cache;
• excludes dependency, build, binary, oversized, generated, and secret-like files before indexing;
• redacts secret patterns again at output time;
• exposes doctor --strict for CI and security checks.

Embeddings are optional. Local embeddings stay on the machine; external embeddings require explicit configuration, an API key, and an endpoint acknowledgement.

See the security model for trust boundaries, gates, failure modes, and residual risks.

How it works

Repository
   │
   ├─ discovery + ignore and secret gates
   ├─ Tree-sitter symbols and relationships
   ├─ line and symbol-aligned chunks
   └─ optional embeddings
          │
          ▼
      local SQLite
   FTS5 + symbols + graph
          │
          ▼
 intent routing → hybrid retrieval → rerank → token budget
          │
          ▼
 ranked file:line evidence for CLI, Skill, and MCP

The three product surfaces share one service layer, so retrieval behavior does not drift between the CLI, installed agent skills, and MCP tools.

Detailed internals:

• Architecture
• Retrieval pipeline
• Database schema
• Language and graph coverage

Supported surfaces

Run the MCP server with:

codebase-index mcp --root /path/to/repository

Available MCP tools include search, explain, symbols, references, impact, diff impact, architecture, shortest path, node description, health, and index statistics. See MCP.md for client configuration.

Project status

The latest released line is 1.9.0. It includes:

• hybrid and optional vector retrieval;
• Tree-sitter symbol extraction across the documented language tiers;
• import, call, reference, and inheritance graphs;
• architecture communities, central nodes, and surprising cross-module links;
• shortest dependency paths and node descriptions;
• token-budgeted and skeletonized retrieval packets;
• benchmark-calibrated lexical expansion, fuzzy identifier matching, and source-aware ranking;
• rank fusion that scores cross-retriever agreement at file level, not just at a locator;
• bounded, intent-directed graph discovery with optional diversity and duplicate suppression;
• CLI, Skill, plugin, and MCP delivery;
• incremental updates, watch hooks, diagnostics, skill rollback, and diff-aware impact analysis;
• a multi-repository retrieval evaluation with leak-free git-derived ground truth, one-signal ablations, and paired significance tests (tests/eval).

Every shipped ranking signal has to survive that evaluation: 1.9.0 removed the cost of two signals that could not demonstrate a benefit and rejected several plausible ones outright (IDF-weighted coverage, stemming, graph propagation, MMR, a file-length prior). Planned work is deliberately separated from shipped capability. The next product priorities are typed framework edges and an even more direct task-context workflow. See the roadmap.

Documentation

Contributing

Contributions should preserve three invariants:

1. retrieval quality is measured, not asserted;
2. the default path remains local and fails closed at security boundaries;
3. machine-readable contracts stay stable across CLI and MCP.

Before opening a pull request:

pytest
ruff check .
mypy src
python scripts/sync_skill_copies.py --check

Add user-visible changes under [Unreleased] in CHANGELOG.md. See CONTRIBUTING.md if present and the repository instructions for branch and review policy.

License

MIT