Code Index

code-index

Claude Code 向けのローカルな SQLite ベースのコードインデックスを、MCP 経由で提供します。見当をつけずに Read / Grep / Glob で探索する代わりに、対象を絞った検索を行います。「parseAuthToken はどこで定義されているか」「何が Indexer.reindex_all を呼び出しているか」「レート制限のコードを探す」といった質問に、オフラインのインデックスを使ってミリ秒単位で回答します。

API キーも外部サービスも不要です。エンベッダーはお使いのマシン上でローカルに動作します。

仕組み（30秒でわかる概要）

1. tree-sitter でリポジトリを解析します（Python、TypeScript/JavaScript、Go、Rust）。
2. コードをシンボルごとに分割し、識別子を展開します（getUserAuthToken → get user auth token）。これにより、どちらの表記でも検索できます。
3. sentence-transformers 経由で jina-embeddings-v2-base-code（768次元）を使い、各チャンクをローカルでベクトル化します。
4. シンボル、チャンク、ベクトル、呼び出し／インポートのエッジを .claude/index.db（SQLite + sqlite-vec + FTS5）に保存します。
5. MCP 経由で 14 個の検索ツールと 1 個の管理ツールを提供します（ツールを参照）。
6. オプションの PostToolUse フックで変更されたファイルを段階的に再インデックスし、最新の状態を保ちます。

ツール

検索

ツール	用途
code_search	概念的なクエリ（例：「認証フロー」「JSON はどこで解析されているか」）に対するハイブリッド（ベクトル + FTS）検索。
symbol_lookup	関数／クラス／メソッド／型を名前で完全一致検索します。識別子を検索する場合は code_search よりもこちらを優先してください。
file_outline	ファイル内のシンボル（シグネチャ付き）をソース順に表示します。概要だけが必要な場合は Read の代わりに使用してください。
module_outline	ディレクトリ階層全体のシンボルを 1 回の呼び出しで表示します。file_outline を繰り返し呼び出す代わりに使用してください。
where_am_i	path と line を指定すると、最も内側のシンボルと、それを囲むシンボルの全階層を返します。
get_symbol_body	symbol_lookup / code_search / file_outline で取得した symbol_id のチャンク全体を返します。
get_symbol_bodies	get_symbol_body の一括版です（1 回の呼び出しにつき最大 20 個の ID）。
callers	指定されたシンボルを呼び出すシンボルを返します。depth（1～5）を指定すると、推移的に展開します。
callees	指定されたシンボルが呼び出すシンボルを返します。depth（1～5）を指定すると、推移的に展開します。
references	呼び出し以外の使用箇所（サブクラス、識別子の直接参照）を返します。callers / callees を補完するツールです。
trace	エントリーシンボルから呼び出しグラフのツリーを構築します。flat=true を指定すると、LLM による軽量なスキャン向けにノード／エッジを返します。
file_imports	このファイルがインポートするファイル（direction=imports）、またはこのファイルをインポートするファイル（direction=imported_by）を返します。
recent_changes	直近の N 件の git コミットで変更されたファイルを返します。
propose_rename	v1：同一ファイル内の名前変更。エージェントが自身の Edit ツールで適用する編集リストを返します。名前が衝突する場合は拒否します。

管理

ツール／操作	目的
admin op=init	インデックスを構築または更新します。デフォルトでは増分処理を行います。force=true を指定すると最初から再構築します。
admin op=setup_check	フックの接続、埋め込みモデル、ホストを診断します。フックのエンドツーエンドのラウンドトリップテストを実行します。
admin op=install_hook	自動再インデックス用の PostToolUse フックを .claude/settings.json に接続します。冪等です。
admin op=stats	読み取り専用：言語ごとのファイル数、シンボルの合計、埋め込みモデルのフィンガープリント、最終インデックス作成時刻を表示します。
admin op=verify	整合性チェック：孤立した行、解析に失敗したファイル、参照先のないエッジを検出します。

embed_query_debug は開発専用のランキング診断ツールです。CODE_INDEX_DEBUG=1 が設定されていない限り、 list_tools には表示されません。

すべてのツールはサイズ制限付きの JSON を返します。大きな本文には、ファイル全体をインライン化するのではなく、 get_symbol_body を使用してください。

要件

• Python 3.10 以降と、ロード可能な SQLite 拡張機能のサポート（sqlite-vec が必要とします）。
  • Python 3.13 では、デフォルトで有効になっています。
  • 3.10～3.12 では、python.org のインストーラーを使用するか、pyenv で PYTHON_CONFIGURE_OPTS=--enable-loadable-sqlite-extensions pyenv install 3.12.x を実行してインストールしてください。
  • Homebrew の Python には拡張機能用のフックが含まれていないことがよくあります。代わりに、上記のいずれかの方法を使用してください。
• uv／uvx（インストール）— 推奨ランナーです。永続的にインストールする場合は pip も使用できます。
• 初回の初期化時に、埋め込みモデル用として約 600 MB の空きディスク容量が必要です。

クイックスタート（Claude Code）

API キー不要のワンコマンドです。

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

次に、任意のリポジトリで Claude Code を開き、次のように尋ねてください。

「このリポジトリのコードインデックスを作成してください。」

Claude は init MCP ツールを呼び出し、.claude/index.db に書き込みます。それ以降は、 「parseAuthToken はどこで定義されていますか？」 や 「Indexer.reindex_all を呼び出しているのは何ですか？」 などと尋ねてください。Claude は grep の代わりに、 symbol_lookup／callers／code_search を通じて検索します。

--refresh の動作 — Claude Code を起動するたびに、PyPI の最新リリースを取得します。 プレビュー中は便利ですが、バージョンを固定したい場合は削除してください（起動時間を約 1 秒短縮できます）。

プロジェクトのみへのインストール — -s user を削除すると、グローバルな ~/.claude.json ではなく、 現在のプロジェクトの .claude/settings.json にサーバーを登録します。

初回実行時のモデルのダウンロード — 最初の init では、 jina-embeddings-v2-base-code（約 600 MB）が ~/.cache/huggingface にダウンロードされ、 その後もキャッシュに保持されます。以降の実行は完全にオフラインで行えます。ネットワークから Hugging Face にアクセスできない場合は、 アクセス可能なマシンから事前にキャッシュを温めてください。

--refresh なしでインストール済みですか？ 先に claude mcp remove code-index を実行してから、 上記のコマンドを再実行してください。

代替方法：永続的なインストール（uvx なし）

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

オプション：編集時にインデックスを最新に保つ

フックがない場合、エージェント以外の操作（mv、 git checkout、IDE による保存）でファイルが変更されると、再度 init を呼び出すまでインデックスが古くなります。フックを設定すると、Claude が実行するすべての Edit／Write／MultiEdit によって、変更されたファイルの増分再インデックスが実行されます。

最も簡単な方法：Claude に依頼する。 新しいプロジェクトで初めて使用するときに、「code-index をセットアップして」 と尋ねてください。Claude が setup_check → install_hook → init を呼び出します。フックのコマンドは MCP サーバーの起動方法から導き出されるため（uvx に対応）、同じ Python ツールチェーンが使用されます。フックの出力は .claude/code-index-hook.log に記録されるため、失敗時のデバッグが可能です。

手動でインストール — プロジェクトの .claude/settings.json の hooks.PostToolUse に次のブロックを追加してください（使用するバージョンはサーバーの起動方法によって異なります。install_hook を使うと適切なものが選ばれます）。

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

その他の MCP 対応エージェント

このサーバーは標準の MCP を stdio 経由で使用するため、MCP サーバーに対応したクライアント（Cursor、Continue、Cody、Zed など）であれば動作します。クライアントに uvx --refresh --from mcp-code-index code-index-mcp（または pip install mcp-code-index の後に code-index-mcp）を起動するよう設定します。接続したら、クライアント内から init ツールを呼び出してインデックスを初期化します。常に最新バージョンを取得するのではなく、安定したバージョンに固定する場合は --refresh を外してください。

ソースから（開発用）

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)

設定

すべての設定は省略可能です。デフォルトのままですぐに使用できます。環境変数で上書きしてください。Claude Code 内では、~/.claude.json の code-index サーバーエントリの env ブロックで設定し、その後 MCP サーバーに再接続します。

よく使う設定（ほとんどのユーザーは通常、以下だけを調整します）：

変数	デフォルト	設定するタイミング
CODE_INDEX_EMBED_DEVICE	auto	torch のデバイスを cpu、mps、cuda のいずれかに固定します。init が MPS のメモリ不足で失敗する場合は、Apple Silicon で cpu を設定します。
CODE_INDEX_EMBED_BATCH	32	エンコードのバッチサイズです。mps／cuda を使い続けながら GPU メモリのピーク使用量を抑えるには、値を小さくします（例：8 や 4）。
CODE_INDEX_DB	.claude/index.db	SQLite インデックスのパスを上書きします（例：同じ親ディレクトリにある複数のワークツリーでインデックスを共有する場合）。

詳細設定（通常は不要です）：

変数	デフォルト	備考
CODE_INDEX_EMBEDDER	jina	現在サポートされているのは jina（ローカルの sentence-transformers）のみです。この変数は将来的な拡張のために用意されています。
CODE_INDEX_EMBED_MODEL	jinaai/jina-embeddings-v2-base-code	Hugging Face のモデル ID です。モデルの次元数が互換性のある（768d）場合のみ上書きしてください。
CODE_INDEX_EMBED_DIM	768	埋め込みモデルの出力次元数と一致させる必要があります。

トラブルシューティング

Apple Silicon で init が MPS backend out of memory により失敗する場合。 大きなファイルによって、GPU の空き VRAM を超えるチャンクのバッチが生成されました。最も手早い解決策は、CPU で再実行することです（遅くなりますが、確実です）。

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

GPU を使い続けるには、代わりにバッチサイズを小さくします。"CODE_INDEX_EMBED_BATCH": "8"。 新しい環境変数を反映するには、MCP サーバーに再接続します（/mcp → 再接続、または Claude Code を再起動）。init は差分更新されるため、再試行時にはすでに埋め込み済みのファイルはスキップされます。

初回実行時に init が Hugging Face のネットワークエラーで失敗する場合。 ネットワークによってモデルのダウンロードがブロックされています。アクセス可能なマシンでキャッシュをあらかじめ温めてください。

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

sqlite3.OperationalError: not authorized が発生する、または sqlite-vec の読み込みに失敗する場合。 お使いの Python ビルドでは、読み込み可能な SQLite 拡張機能が有効になっていません。要件を参照し、python.org からインストールするか、PYTHON_CONFIGURE_OPTS=--enable-loadable-sqlite-extensions を指定して pyenv でビルドしてください。

リファクタリングやブランチのチェックアウト後に code_search／symbol_lookup が古いパスを返す場合。 自動再インデックスフックが実行されるのは、Claude の Edit／Write／MultiEdit のみです。エージェント以外の手段（mv、git checkout、IDE の名前変更）で多数のファイルを移動した後は、init を再実行してください（差分更新されます）。または、フックを設定すると、エージェントによる編集に合わせてインデックスが自動的に更新されます。

構成

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