code-index

A SQLite-backed code index for Claude Code, exposed via MCP. Replaces exploratory Read/Grep/Glob calls with targeted retrieval.

What it does

Parses your repo with tree-sitter (Python, TypeScript/JavaScript, Go, Rust).
Chunks per symbol; expands identifiers (getUserAuthToken → get user auth token).
Embeds with Voyage voyage-code-3 (default) or local Ollama.
Stores symbols, chunks, vectors, and call/import edges in .claude/index.db.
Serves retrieval over MCP — 8 retrieval tools + 1 admin tool (see below).
Auto-updates via a Claude Code PostToolUse hook and an optional file watcher.

Tools

Tool	Purpose
`init`	Build or refresh the project's index. Incremental by default; `force=true` rebuilds from scratch.
`code_search`	Hybrid (vector + FTS) search for conceptual queries (e.g., "auth flow", "where do we parse JSON").
`symbol_lookup`	Exact-name lookup of functions / classes / methods / types. Prefer over `code_search` for identifiers.
`file_outline`	Symbols (with signatures) in a file, in source order. Use instead of `Read` when you only need shape.
`get_symbol_body`	Full chunk for a `symbol_id` returned by `symbol_lookup` or `code_search`.
`callers`	Symbols that CALL the given symbol. `depth` (1-5) expands transitively.
`callees`	Symbols that the given symbol CALLS. `depth` (1-5) expands transitively.
`dependents`	Files that import the given file.
`dependencies`	Files that the given file imports.

All tools return bounded JSON; large bodies use get_symbol_body rather than inlining whole files.

Requirements

Python with loadable SQLite extension support (required by sqlite-vec). Python 3.13 has this enabled by default. For 3.10–3.12, use either:

the python.org installer, or
pyenv: PYTHON_CONFIGURE_OPTS=--enable-loadable-sqlite-extensions pyenv install 3.12.x

Install

In Claude Code (primary)

# 1. Set your embedder API key (Voyage default; for local Ollama see Configuration)
export VOYAGE_API_KEY=...

# 2. Register the MCP server. uvx clones, builds, and runs — no global install.
claude mcp add code-index -- uvx --from git+https://github.com/achreftlili/code-index code-index-mcp

That's it. Open Claude Code in your repo and ask:

"Build the code index for this repo."

Claude calls the init MCP tool, which writes .claude/index.db. Subsequent prompts can use code_search, symbol_lookup, callers, etc. — see Tools above for the full surface.

Or, with a permanent install

pip install mcp-code-index
claude mcp add code-index -- code-index-mcp

Optional: keep the index live as you edit

Without the hook below, the index drifts when files change outside the agent (mv, git checkout, IDE saves) until you call init again. With it, every Edit / Write / MultiEdit Claude performs triggers an incremental reindex of the touched file:

git clone https://github.com/achreftlili/code-index ~/code-index
~/code-index/scripts/install-hook.sh /path/to/your/repo   # idempotent

In other MCP-compatible agents

The server speaks standard MCP over stdio, so any client that supports MCP servers works (Cursor, Continue, Cody, Zed, etc.). Configure the client to launch code-index-mcp (after pip install) or the uvx --from git+… command above. Once connected, call the init tool from inside the client to bootstrap the index.

From source (development)

git clone https://github.com/achreftlili/code-index
cd code-index
pip install -e .
code-index init        # CLI alternative to the `init` MCP tool
code-index-mcp         # starts the MCP server on stdio (for manual wiring)

Configuration

Environment variables:

Var	Default	Notes
`CODE_INDEX_DB`	`.claude/index.db`	SQLite path.
`CODE_INDEX_EMBEDDER`	`voyage`	`voyage` or `ollama`.
`CODE_INDEX_EMBED_MODEL`	`voyage-code-3`	Model name.
`CODE_INDEX_EMBED_DIM`	`1024`	Must match the model.
`VOYAGE_API_KEY`	—	Required when `CODE_INDEX_EMBEDDER=voyage`.
`OLLAMA_URL`	`http://localhost:11434`	Ollama server.

Layout

src/code_index/
  db.py           SQLite schema, connection, sqlite-vec loading
  parser.py       Tree-sitter wrapper, symbol + edge extraction
  chunker.py      Per-symbol chunks, identifier expansion
  embedder.py     Voyage / Ollama backends
  indexer.py      Pipeline: walk → parse → chunk → embed → write
  retriever.py    Hybrid search (vector + FTS5) with RRF
  watcher.py      File watcher (watchdog)
  mcp_server.py   8 MCP tools
  cli.py          init / reindex / watch / stats

Code Index

Quick Install