Code Index

io.github.achreftliliPublished by GitHub account achreftliliv1.0.6Updated Oct 24, 2026

SQLite-backed hybrid (vector + FTS) code search index for Claude Code over MCP.

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

Local SQLite-backed hybrid vector and full-text code index that lets an assistant search symbols, outlines and call graphs in a repository instead of grepping.

What you can do
  • Search code by concept with hybrid vector plus full-text search, or look up exact symbol names
  • Outline files and whole directory subtrees, and locate the enclosing symbol for a file position
  • Fetch symbol bodies individually or in batches
  • Trace call graphs: callers, callees, references, transitive traces, and file imports
  • List files touched in recent git commits and propose same-file renames as an edit list
  • Administer the index: build or refresh it, check setup, install the auto-reindex hook, show stats and verify integrity
When to use it
Useful when an assistant works in a medium or large repository and should answer questions like where a function is defined, what calls it, or where a concept lives, without reading whole files. Best for Python, TypeScript/JavaScript, Go and Rust codebases where fast offline retrieval beats blind file reads.
Requirements
Runs locally over stdio as a PyPI package (mcp-code-index), typically launched with uvx or installed with pip. Needs Python 3.10+ with loadable SQLite extension support for sqlite-vec, and about 600 MB of disk for the embedding model, which is downloaded from Hugging Face on first init. No API keys or accounts. Optional environment variables such as CODE_INDEX_DB, CODE_INDEX_EMBED_DEVICE and CODE_INDEX_EMBED_BATCH tune the index path and embedding device.
Before you install
The first init downloads a roughly 600 MB model from Hugging Face, so it needs network access once. The optional hook writes to the project's .claude/settings.json and re-indexes files on every edit, and the index database is written under .claude/index.db by default. The index goes stale after file moves or branch checkouts outside the agent until init is re-run. The rename tool only returns an edit list for the agent to apply.

Installation

In SourceWeft

  1. Open Code Index in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

ToolPurpose
code_searchHybrid (vector + FTS) search for conceptual queries (e.g., "auth flow", "where do we parse JSON").
symbol_lookupExact-name lookup of functions / classes / methods / types. Prefer over code_search for identifiers.
file_outlineSymbols (with signatures) in a file, in source order. Use instead of Read when you only need shape.
module_outlineSymbols across a directory subtree in one call. Use instead of looping file_outline.
where_am_iGiven path + line, returns the innermost symbol and the full enclosing chain.
get_symbol_bodyFull chunk for a symbol_id from symbol_lookup / code_search / file_outline.
get_symbol_bodiesBatch version of get_symbol_body (up to 20 ids per call).
callersSymbols that CALL the given symbol. depth (1-5) expands transitively.
calleesSymbols that the given symbol CALLS. depth (1-5) expands transitively.
referencesNon-call uses (subclasses, free identifier references). Companion to callers / callees.
traceBuild a call-graph tree from an entry symbol; flat=true returns nodes/edges for cheap LLM scans.
file_importsFiles this file imports (direction=imports) or that import it (direction=imported_by).
recent_changesFiles touched in the last N git commits.
propose_renamev1: same-file rename. Returns an edit list the agent applies via its own Edit tool; refuses on clash.

Admin

Tool / opPurpose
admin op=initBuild or refresh the index. Incremental by default; force=true rebuilds from scratch.
admin op=setup_checkDiagnose hook wiring + embedder + host. Round-trip-tests the hook end-to-end.
admin op=install_hookWire the auto-reindex PostToolUse hook into .claude/settings.json. Idempotent.
admin op=statsRead-only: file counts by language, symbol totals, embed model fingerprint, last-index time.
admin op=verifyIntegrity sweep: orphan rows, parse-failure files, dangling edges.

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:

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

bash
pip install mcp-code-indexclaude 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):

json
{  "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)

bash
git clone https://github.com/achreftlili/code-indexcd code-indexpip install -e .code-index init        # CLI alternative to the `init` MCP toolcode-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):

VarDefaultWhen to set it
CODE_INDEX_EMBED_DEVICEautoForce the torch device: cpu, mps, or cuda. Set cpu on Apple Silicon if init fails with MPS out-of-memory.
CODE_INDEX_EMBED_BATCH32Encode batch size. Lower (e.g. 8 or 4) to cut peak GPU memory while staying on mps/cuda.
CODE_INDEX_DB.claude/index.dbOverride the SQLite index path (e.g. to share an index across sibling worktrees).

Advanced (rarely needed):

VarDefaultNotes
CODE_INDEX_EMBEDDERjinaOnly jina (local sentence-transformers) is supported today; the variable exists for future expansion.
CODE_INDEX_EMBED_MODELjinaai/jina-embeddings-v2-base-codeHuggingFace model id. Only override if you know the model is dim-compatible (768d).
CODE_INDEX_EMBED_DIM768Must match the embedding model's output dimension.

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

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

To stay on the GPU, shrink the batch instead: "CODE_INDEX_EMBED_BATCH": "8". Reconnect the MCP server (/mcp → reconnect, or restart Claude Code) so the new env takes effect. init is incremental — already-embedded files are skipped on the retry.

init fails with a Hugging Face network error on first run. Your network is blocking model downloads. Pre-warm the cache on a machine that has access:

bash
huggingface-cli download jinaai/jina-embeddings-v2-base-code# then copy ~/.cache/huggingface/ to the offline machine

sqlite3.OperationalError: not authorized or sqlite-vec fails to load. Your Python build doesn't have loadable SQLite extensions. See Requirements — install via python.org or a pyenv build with PYTHON_CONFIGURE_OPTS=--enable-loadable-sqlite-extensions.

code_search / symbol_lookup returns stale paths after a refactor or branch checkout. The auto-reindex hook only fires on Claude's Edit / Write / MultiEdit. After bulk file moves outside the agent (mv, git checkout, IDE rename), re-run init (it's incremental). Or wire up the hook so the index keeps up with agent edits automatically.

Layout

src/code_index/  db.py           SQLite schema, connection, sqlite-vec loading  parser.py       Tree-sitter wrapper, symbol + edge extraction  imports.py      Per-language import target → file path resolution  chunker.py      Per-symbol chunks, identifier expansion  embedder.py     Local Jina (sentence-transformers) backend  indexer.py      Pipeline: walk → parse → chunk → embed → write  reindexer.py    Per-root engine cache; one entry point for "reindex one file"  retriever.py    Hybrid search (vector + FTS5) with RRF  watcher.py      File watcher (watchdog)  admin.py        setup_check / install_hook / init logic (pure, no MCP state)  mcp_server.py   MCP wiring, shared helpers, schema fragments  tool_registry.py  Shared `@_tool` decorator + `_TOOLS` registry  tools/          Per-domain MCP handlers (graph, paths, refactor, …)  hook.py         `code-index-hook` console script — the PostToolUse entry point  cli.py          init / reindex / watch / stats

Source: README.md at commit 27a6bf8

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.6LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts