code-index

A local, SQLite-backed code index for Claude Code, exposed over MCP. It replaces blind Read / Grep / Glob exploration with targeted retrieval — "where is parseAuthToken defined", "what calls Indexer.reindex_all", "find the rate-limiting code" — answered in milliseconds against an offline index.

No API keys. No external services. The embedder runs locally on your machine.

How it works (30-second tour)

1. Parse your repo with tree-sitter (Python, TypeScript/JavaScript, Go, Rust).
2. Chunk code per symbol and expand identifiers (getUserAuthToken → get user auth token) so search matches both styles.
3. Embed each chunk locally with jina-embeddings-v2-base-code (768-dim) via sentence-transformers.
4. Store symbols, chunks, vectors, and call/import edges in .claude/index.db (SQLite + sqlite-vec + FTS5).
5. Serve 14 retrieval tools + 1 admin tool over MCP (see Tools).
6. Stay fresh via an optional PostToolUse hook that incrementally re-indexes touched files.

Tools

Retrieval

Admin

embed_query_debug is a dev-only ranking diagnostic, hidden from list_tools unless CODE_INDEX_DEBUG=1 is set.

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

Requirements

• Python 3.10+ with loadable SQLite extension support (required by sqlite-vec).
  • Python 3.13 has this enabled by default.
  • On 3.10–3.12, install via the python.org installer or via pyenv with PYTHON_CONFIGURE_OPTS=--enable-loadable-sqlite-extensions pyenv install 3.12.x.
  • Homebrew Python often ships without the extension hook — use one of the two methods above instead.
• uv / uvx (install) — recommended runner. Or pip if you prefer a permanent install.
• ~600 MB free disk for the embedding model on first init.

Quick start (Claude Code)

One command, no API keys:

claude mcp add-json -s user code-index "$(cat <<'JSON'
{
  "type": "stdio",
  "command": "uvx",
  "args": ["--refresh", "--from", "mcp-code-index", "code-index-mcp"]
}
JSON
)"

Then open Claude Code in any repo and ask:

"Build the code index for this repo."

Claude calls the init MCP tool, which writes .claude/index.db. From then on, ask things like "where is parseAuthToken defined?" or "what calls Indexer.reindex_all?" — Claude routes them through symbol_lookup / callers / code_search instead of grepping.

What --refresh does — fetches the latest PyPI release on every Claude Code launch. Convenient during preview; drop it once you want to pin a version (saves ~1s of startup).

Project-only install — drop -s user to register the server in the current project's .claude/settings.json instead of the global ~/.claude.json.

First-run model download — the first init pulls jina-embeddings-v2-base-code (~600 MB) into ~/.cache/huggingface and caches it forever. Subsequent runs are fully offline. If your network blocks Hugging Face, pre-warm the cache from a machine that has access.

Already installed without --refresh? Run claude mcp remove code-index first, then re-run the command above.

Alternative: permanent install (no uvx)

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

Optional: keep the index live as you edit

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

Easiest path: ask Claude. On first use in a new project, ask "set up the code-index" — Claude calls setup_check → install_hook → init. The hook command is derived from how the MCP server was launched (uvx-aware), so it uses the same Python toolchain. Hook output goes to .claude/code-index-hook.log so failures are debuggable.

Manual install — add this block to the project's .claude/settings.json under hooks.PostToolUse (the version you want depends on how you launch the server — install_hook derives the right one for you):

{
  "matcher": "Edit|Write|MultiEdit",
  "hooks": [
    {
      "type": "command",
      "command": "uvx --with 'sentence-transformers<5' --with 'numpy<2' --from mcp-code-index code-index-hook"
    }
  ]
}

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 uvx --refresh --from mcp-code-index code-index-mcp (or code-index-mcp after pip install mcp-code-index). Once connected, call the init tool from inside the client to bootstrap the index. Drop --refresh when you want to pin to a stable version instead of always pulling latest.

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

All settings are optional — the defaults work out of the box. Override them via environment variables. Inside Claude Code, set them in the env block of your code-index server entry in ~/.claude.json (then reconnect the MCP server).

Common knobs (most users only ever touch these):

Advanced (rarely needed):

Troubleshooting

init fails with MPS backend out of memory on Apple Silicon. A large file produced a chunk batch bigger than your GPU's free VRAM. Quickest fix — re-run on CPU (slower but bulletproof):

"env": {
  "CODE_INDEX_EMBED_DEVICE": "cpu"
}