Codebase Index

codebase-index: Local Codebase Indexing for AI Coding Agents

codebase-index is a local-first codebase indexing tool that helps Claude Code, Codex CLI, OpenCode, and other AI coding agents find relevant files, symbols, and references without scanning an entire repository.

[](LICENSE) [](https://www.python.org/) [](https://github.com/denfry/codebase-index/actions) [](skill/SKILL.md) [](#which-ai-clis-does-codebase-index-support) [](#which-ai-clis-does-codebase-index-support) [](docs/MCP.md) [](#safety-and-privacy) [](#safety-and-privacy) [](#safety-and-privacy) [](docs/DATABASE_SCHEMA.md) [](docs/ARCHITECTURE.md)

What Is codebase-index?

codebase-index is a private, offline retrieval layer for AI code search. It builds a SQLite index of your repository, extracts symbols with Tree-sitter, ranks matches with hybrid retrieval, and returns compact file:line ranges that an AI coding agent can read instead of opening broad file sets.

Use it when you want Cursor-like codebase awareness in terminal-based AI tools while keeping source code, snippets, and search metadata on your machine.

> codebase-index is not an IDE and not a coding agent. It is the local > retrieval/index layer that gives terminal and MCP-based AI agents precise > codebase context. The agent stays your interface; this gives it better aim.

Who Is It For?

• Claude Code / Codex CLI / OpenCode users on medium-to-large repos who want

the agent to read 3 ranked files instead of grepping and scanning 60.

• Privacy-constrained teams (proprietary or regulated code) who cannot send

source to a cloud code-intelligence service.

• MCP power users who want a stable, queryable code index as a tool, not a

black box baked into one agent's prompt.

• Tooling authors who need scriptable retrieval (--json, SQLite, MCP) that

other tools can build on.

Not for you if you want a full IDE, org-scale multi-repo search, or a hosted platform — use Cursor or Sourcegraph for those.

Start Here

If you are opening this repository for the first time, follow this order:

1. [Quick Start (5 minutes)](docs/QUICKSTART.md)
2. [Installation Guide](docs/INSTALLATION.md)
3. [Benchmarks](docs/BENCHMARKS.md)
4. [How the skill works](skill/SKILL.md)
5. [MCP server](docs/MCP.md)
6. [FAQ](docs/FAQ.md)

If you only need the shortest path, run:

pip install codebase-index     # from PyPI
cd your-project
codebase-index init            # prompts for Claude Code / Codex CLI / OpenCode
codebase-index index
codebase-index search "where is authentication implemented?"

Project Status

1.6.0 is released. The current release includes repository discovery, SQLite FTS5 storage, Tree-sitter symbols and references, hybrid ranking, graph impact analysis, token-budgeted retrieval packets, optional local embeddings, hooks/watch support, multi-CLI installation, MCP server support, and PyPI + pipx install paths (pip install codebase-index).

The 1.6.0 release turns the dependency graph into a navigable map: every edge carries a confidence audit trail (extracted/inferred/ambiguous, surfaced in refs/impact); a new zero-dependency analytics pass computes modules (communities), god nodes, and surprising cross-module links, exposed via the architecture command/MCP tool; path traces the shortest dependency chain between two symbols and describe prints a symbol's node card; and the HTML graph is coloured by module and sized by connectivity, with --format graphml|dot|neo4j exports for external tools. Requires a one-time reindex (schema 2 → 3).

The earlier 1.4.0 release hardened the MCP contract (a schema_version + tool envelope on every payload, golden-locked per tool, plus a fix so the server loads on current mcp/pydantic), dampened the god-class in_degree rerank tiebreak (logarithmic, validated no-regression on the public benchmark), and labelled config/IaC files (Dockerfile, Terraform, HCL, INI, Makefiles) so infra surfaces in stats and search.

The earlier 1.3.0 release added a content-addressed embedding cache (rebuilds reuse vectors for unchanged content), a batched graph build (7–28× faster edge resolution plus a new edges(file_id) index), a shared CLI/MCP service layer (MCP hybrid search now uses the vector channel; index_stats reports the per-language graph tier), graph-coverage signals in stats/refs/impact, CLI pagination via search --offset, and single-source versioning with a CI gate that keeps every committed skill copy in sync. The 1.2.1 release added skill auto-update/rollback commands and version stamps so installed skills stay in sync with the package automatically. See [CHANGELOG.md](CHANGELOG.md) and [docs/ROADMAP.md](docs/ROADMAP.md).

MCP is now available as a stdio server via codebase-index mcp --root . It exposes healthcheck, search_code, find_symbol, find_refs, impact_of, explain_code, architecture_overview, path_between, describe_symbol, and index_stats; see [docs/MCP.md](docs/MCP.md).

You:   "Where is user authentication implemented?"
Agent: searches local index (symbols + FTS5 + graph)
       reads only 3 ranked files instead of scanning 60
       answers with citations: src/auth/AuthService.ts:12-148

---

How Do I Install codebase-index?

For most users, install the package from PyPI and run init inside the repository you want to index:

pip install codebase-index     # or: pipx install codebase-index
cd your-project
codebase-index init            # choose Claude Code, Codex CLI, OpenCode, or all
codebase-index index

In a non-interactive script, pass a target explicitly:

codebase-index init --target auto      # install into detected AI CLIs
codebase-index init --target codex     # write AGENTS.md + Codex resources
codebase-index init --target claude    # write .claude/skills/codebase-index
codebase-index init --target opencode  # write OpenCode command + agent files

Install as a Claude Code plugin

One command in Claude Code:

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

Or just ask: "install the codebase-index plugin".

What happens on first run: when a session starts, a SessionStart hook (scripts/bootstrap.sh / .ps1) creates a private Python virtual environment under ~/.claude/plugins/data/codebase-index-*/venv and installs the pinned codebase-index package (from requirements.lock) into it — using uv if present, otherwise python -m venv + pip. It reinstalls only when the lock file changes. Nothing is installed globally; uninstalling the plugin removes the data directory.

Prerequisite: Python 3.11+ on your PATH. The first install needs network access to fetch the package; later sessions are offline. The skill builds its index on your first codebase question, so there is no manual index step.

Distribution note: the plugin bootstrap installs the pinned requirement from requirements.lock. In 1.6.0, that lock points at the tagged GitHub release instead of PyPI. You can override it with CBX_INSTALL_SPEC when testing a local checkout or a different Git ref.

What Problem Does codebase-index Solve?

AI coding agents struggle with large repositories when they rely on broad file reads, grep output, or user-provided context. codebase-index gives those agents a ranked local retrieval packet before they read source files.

• Token waste — Scanning entire files or running broad grep/glob queries burns through the context window on irrelevant content.
• No symbol awareness — Standard search can't distinguish a function definition from a call, or a class from a variable.
• No ranking — Grep returns all matches with no relevance ordering. The agent must read everything.
• No context — Grep doesn't know which files are related or what to read next.
• Cloud dependency — External code indexing services send your proprietary code to remote servers.

Developers get Cursor-like codebase awareness in Claude Code, Codex CLI, and OpenCode without leaving the terminal or sending code to a remote indexing service.

How Is This Different?

Short answers to the questions people actually ask. The full, honest matrix — including when you should pick the other tool — is in [docs/COMPARISON.md](docs/COMPARISON.md).

• Why not just grep/rg? Grep returns every match with no ranking, no

symbol awareness, and no idea which files relate. codebase-index ranks results, knows a definition from a call, expands along the dependency graph, and returns specific line ranges under a token budget — so the agent reads less and answers with citations.

• Why not Cursor? Cursor is a great AI IDE with strong codebase awareness, but

it is proprietary and IDE-centric. codebase-index is a local, open retrieval layer for terminal and MCP agents, offline by default, with no IDE lock-in. If you live inside Cursor, keep using Cursor.

• Why not Aider repo-map? Aider's repo-map is a good graph-ranked,

token-budgeted context map — but it is optimized to feed Aider's own chat. codebase-index is a reusable, queryable index: CLI/JSON/MCP commands return ranked file:line ranges, symbols, references, and impact that any shell-capable agent can consume, with freshness and security gates.

• Why not Sourcegraph / Cody / Amp? They are excellent enterprise-grade,

cross-repo code intelligence platforms. They are also heavier and account/platform-oriented. codebase-index is single-repo, local, and lightweight — no server, no account, no code leaving the machine by default.

• Why not Codebase-Memory MCP? It is the closest direct alternative — a

broader graph engine with a static binary and wide language/agent coverage. We do not claim to beat it globally. We differentiate on simplicity, a strict privacy model, token-budgeted retrieval packets, a transparent Python implementation, the Claude/Codex/OpenCode workflow, and honest benchmarks. If you need its broader graph and language reach today, choose it.

What makes it trustworthy? No telemetry, no network by default, a multi-gate exclusion pipeline (secrets/binaries/generated/dependencies never indexed), output-time secret redaction, a doctor --strict safety self-check, and a public benchmark suite wired as a CI regression gate. Claims that aren't proven in this repo are marked as roadmap, not done.

Proven today vs. roadmap

| Capability | Status | |---|---| | Hybrid retrieval (path + symbol + FTS5 + graph), token-budgeted packets | ✅ Shipped | | Tree-sitter symbols for 12 Tier-A languages + Tier-B generic path | ✅ Shipped | | Import/call/reference/inheritance graph, refs/impact | ✅ Shipped | | Optional local embeddings; external embeddings gated 3 ways | ✅ Shipped | | stdio MCP server; CLI/skill/MCP share one service layer | ✅ Shipped | | Honest 55k LOC Java benchmark (recall@3 70% vs 40% rg, ~13× fewer tokens) | ✅ Shipped | | 10k/100k/1M LOC public-repo benchmarks | 🚧 Roadmap | | Framework-aware typed edges (route→handler→service→model) | 🚧 Roadmap | | PyPI / uvx / Homebrew, signed checksums, SBOM | 🚧 Roadmap | | Verified per-client MCP docs, paged/progressive results | 🚧 Roadmap |

See [docs/PRODUCTUPGRADEPLAN.md](docs/PRODUCTUPGRADEPLAN.md) for the full upgrade plan and ranked roadmap.

How Does codebase-index Work?

codebase-index builds a local hybrid index that combines:

• Symbol search — Tree-sitter AST parsing extracts classes, functions, methods, and variables across the supported code-language set.
• Full-text search — SQLite FTS5 for fast lexical search across code chunks.
• Path search — File path matching for location-aware queries.
• Optional semantic search — Vector embeddings for similarity-based retrieval (opt-in, local by default).
• Dependency graph — Import, call, and reference edges for impact analysis and graph expansion.
• Token-budgeted output — Ranked retrieval packets with specific line ranges, not whole files.

The AI agent reads only the recommended files and line ranges, not the entire repository.

Quick Demo

/codebase-index "where is user authentication implemented?"

Expected output:

Top matches:
┌──────┬──────────────────────────┬──────────────────────────┬───────┬──────────────────────────────┐
│ Rank │ Path                     │ Symbols                  │ Score │ Reason                       │
├──────┼──────────────────────────┼──────────────────────────┼───────┼──────────────────────────────┤
│    1 │ src/auth/AuthService.ts  │ AuthService, login       │  0.92 │ exact symbol match           │
│    2 │ src/routes/auth.ts       │ loginHandler, logout     │  0.78 │ FTS match · 4 callers        │
│    3 │ src/middleware/auth.ts   │ requireAuth              │  0.65 │ path match · FTS match       │
└──────┴──────────────────────────┴──────────────────────────┴───────┴──────────────────────────────┘

Recommended reads:
  1. src/auth/AuthService.ts:12-148
     reason: matched AuthService, login(), validatePassword()
  2. src/routes/auth.ts:20-91
     reason: /login route calls AuthService.login()
  3. src/middleware/auth.ts:5-42
     reason: auth middleware validates sessions

Installation Options

If you are new to this repo, start with [docs/QUICKSTART.md](docs/QUICKSTART.md). If you want all install options and troubleshooting, use [docs/INSTALLATION.md](docs/INSTALLATION.md).

Multi-CLI installer (Claude Code + Codex CLI + OpenCode): one command via install.sh / install.ps1 — see [docs/installer.md](docs/installer.md).

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/denfry/codebase-index/main/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/denfry/codebase-index/main/install.ps1 | iex

Option 1: Install from PyPI (recommended)

pip install codebase-index        # or: pipx install codebase-index
cd your-project
codebase-index init
codebase-index index

Option 2: Pin to a tagged GitHub release

Pin to an exact version for reproducible installs, or grab an unreleased commit:

cd your-project
pip install "codebase-index @ git+https://github.com/denfry/codebase-index.git@v1.6.0"
codebase-index init
codebase-index index

Python version compatibility

codebase-index requires Python 3.11 or newer.

If codebase-index init --target opencode fails with:

ModuleNotFoundError: No module named 'importlib.resources.abc'; 'importlib.resources' is not a package

the pipx environment was likely created with an older Python version. Reinstall codebase-index using Python 3.11+ explicitly:

pipx uninstall codebase-index
py -0p
pipx install --python "\python.exe" codebase-index

For example:

pipx install --python "C:\Users\you\AppData\Local\Programs\Python\Python312\python.exe" codebase-index

Then run initialization again:

codebase-index init --target opencode
codebase-index index

Option 3: Install with pipx from a pinned GitHub tag

pipx install "git+https://github.com/denfry/codebase-index.git@v1.6.0"
cd your-project
codebase-index init --target auto
codebase-index index

Option 4: Install from source

git clone https://github.com/denfry/codebase-index.git
cd codebase-index
pip install -e ".[dev]"

Distribution roadmap

As of 1.6.0, PyPI is shipped — pip install codebase-index and pipx install codebase-index work today. uvx, Homebrew, signed release checksums, and SBOMs remain on the roadmap:

uvx codebase-index init                  # planned
brew install denfry/tap/codebase-index   # planned

Verify the install

codebase-index doctor

See [docs/INSTALLATION.md](docs/INSTALLATION.md) for the full guide, including optional extras (embeddings,

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: denfry
• Source: denfry/codebase-index
• License: MIT

Install and usage instructions live in the source repository linked above.