# Codebase Index

> Local-first codebase indexing for Claude Code, Codex CLI, OpenCode & AI coding agents — hybrid FTS5 + Tree-sitter + graph search, fully offline.

- **Type:** MCP server
- **Install:** `agentstack add mcp-denfry-codebase-index`
- **Verified:** Pending review
- **Seller:** [denfry](https://agentstack.voostack.com/s/denfry)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [denfry](https://github.com/denfry)
- **Source:** https://github.com/denfry/codebase-index

## Install

```sh
agentstack add mcp-denfry-codebase-index
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
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:

```bash
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:

```bash
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/PRODUCT_UPGRADE_PLAN.md](docs/PRODUCT_UPGRADE_PLAN.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

```bash
/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).

```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/denfry/codebase-index/main/install.sh | sh
```
```powershell
# Windows PowerShell
irm https://raw.githubusercontent.com/denfry/codebase-index/main/install.ps1 | iex
```

### Option 1: Install from PyPI (recommended)

```bash
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:

```bash
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:

```text
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:

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

For example:

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

Then run initialization again:

```powershell
codebase-index init --target opencode
codebase-index index
```

### Option 3: Install with pipx from a pinned GitHub tag

```bash
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

```bash
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:

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

### Verify the install

```bash
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](https://github.com/denfry)
- **Source:** [denfry/codebase-index](https://github.com/denfry/codebase-index)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-denfry-codebase-index
- Seller: https://agentstack.voostack.com/s/denfry
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.