codeindex

AI コーディングエージェント向けの MCP サーバー として動作する、構造的なコードインテリジェンスエンジンです。

tree-sitter（40 以上の言語）でコードベースをインデックス化し、トライグラム全文検索インデックス、転置語インデックス、依存関係グラフを構築し、それらを 16 個の MCP ツール を通じて公開します。

 ┌─────────────┐   MCP (stdio)   ┌───────────┐            ┌──────────────────┐
 │  AI Agent   │ ◄─────────────► │ codeindex │  socket    │ codeindex daemon │
 │ (Claude,    │ 16 tools,       │  (relay)  │ ◄────────► │  one per         │
 │  Cursor…)   │ JSON-RPC        └───────────┘            │  workspace       │
 └─────────────┘                                          └────────┬─────────┘
 ┌─────────────┐   MCP (stdio)   ┌───────────┐                     │
 │  AI Agent   │ ◄─────────────► │ codeindex │ ◄───────────────────┘
 │  (session 2)│                 │  (relay)  │   tree-sitter parse (40+ langs)
 └─────────────┘                 └───────────┘   trigram + word index
                                                 dependency graph
                                                 one file watcher
                                                 snapshot persistence

リポジトリに接続する各セッションは、これまでどおりプレーンな stdio MCP を使用します。その裏側では、接続しているエージェントの数にかかわらず、インデックスは共有されます。ツリーの解析、監視、書き込みはそれぞれ一度だけ行われます。以前は、1 つのリポジトリで 8 つのセッションを実行すると、同じインデックスのコピーが 8 つ、ファイルウォッチャーが 8 つ、同じスナップショットを書き込むプロセスが 8 つありました。720 ファイルのプロジェクトで計測したところ、1 セッションあたり 87 MB から 7 MB になり、共有デーモンの 77 MB と合わせて使用されるようになりました。

理由

AI コーディングエージェントは、ファイル全体を読み取るためにトークンを消費します。codeindex は、シンボルの概要、定義、呼び出し元、影響範囲、依存関係の連鎖といった構造に関する質問に、数千トークンではなく数百トークンで答えます。

1 回の plan_change 呼び出しで、シンボルの定義場所、すべての呼び出し箇所、ファイルのアーキテクチャ上の役割（god module／stable core／island／driver）、確認が必要なハードコードされたリテラル、そしてファイル変更時の完全な推移的影響範囲が返されます。

クイックスタート

Node 18+ をお使いの場合の最短手順です。それ以外のインストールやキー、設定は不要です。このパッケージは 4 KB のラッパーで、使用するプラットフォーム向けのバイナリを取得し、公開済みのチェックサムと照合して検証します。

claude mcp add codeindex -- npx -y @munhq/codeindex

Node を使わない場合、またはスキルとフックも必要な場合：

# Prebuilt binary + skill + MCP registration, in one command
curl -fsSL https://raw.githubusercontent.com/munhq/codeindex/main/install.sh | sh

# Or build from source:
cd zig && ./fetch-vendor.sh && zig build -Doptimize=ReleaseFast

MCP サーバーをイメージとしてインストールするホスト向けの Docker です。ワークスペースは読み取り専用でバインドマウントされ、codeindex が書き込むことはありません。

docker run -i --rm -v "$PWD:/workspace:ro" munhq/codeindex

AI エージェントに登録します：

# Claude Code — the plugin is the one-step path. It ships the skill, both
# routing hooks and the MCP server together, and its launcher finds or fetches
# the binary.
claude plugin marketplace add munhq/codeindex
claude plugin install codeindex@codeindex

# Without the plugin (or for a different MCP client), register the binary
# directly. Do not do both: two registrations mean two servers, two copies of
# every tool schema, and two writers on one snapshot. install.sh detects the
# plugin and skips this step when it is present.
claude mcp add -s user codeindex -- ~/.local/bin/codeindex --mcp

# Cursor / Claude Desktop / other MCP clients: add to your config
{
  "mcpServers": {
    "codeindex": {
      "command": "npx",
      "args": ["-y", "@munhq/codeindex"]
    }
  }
}

どの掲載先からも同じサーバーを利用できます。npm の @munhq/codeindex、公式 MCP レジストリの io.github.munhq/codeindex、Smithery の munhq/codeindex です。

次回エージェントを起動すると、codeindex はバックグラウンドでプロジェクトをインデックス化し、構造に関するクエリを提供します。

MCP ツール

ツール	機能
status	インデックスの統計情報：ファイル数、シンボル数、インデックス作成状態、トークン削減率、インデックス化された workspace、および watcher が稼働中かどうか
search	インデックス化されたすべてのファイルを対象とした、トライグラムで高速化された全文検索
find_symbol	名前を指定してシンボル定義（関数、構造体、クラスなど）を検索
find_word	逆引き単語インデックスで、単語や識別子を完全一致検索
find_callers	シンボルの呼び出し箇所と、そのシンボルを含む関数。同名で照合するため、別の場所にある同名の定義も含まれます
get_outline	ファイルの構造概要（シンボル、行数）
get_tree	ファイルメタデータを含むディレクトリツリー
get_imports	指定したファイルがインポートまたは依存しているファイル
get_imported_by	逆依存関係 — このファイルをインポートしているファイル
get_change_impact	推移的な影響範囲：ファイルを変更した場合に何が壊れるか
plan_change	シンボルまたはファイルの完全なリファクタリング計画 — 定義、呼び出し元、ファイルの役割、リテラル、影響範囲
get_hot_files	最近変更されたファイルを新しい順に表示
read_file	任意の行範囲を指定してファイルの内容を読み取る
read_symbol	シンボルのソースコードのみを読み取る（前後の行も任意で指定可能）
index_workspace	ワークスペースディレクトリをインデックス化または再インデックス化
analyze	22 種類のコード解析のいずれかを実行（以下を参照）

解析（analyze ツール）

解析	検出対象
security	ハードコードされたシークレット、SQL インジェクションのパターン、安全でないブロック、eval の使用
dead_code	独自の定義以外では名前が参照されないシンボル。ライブラリパッケージの未使用パブリック API とは分けて検出
unwrap_audit	.unwrap()／expect／panic! の箇所（Rust）。リクエストハンドラー、ループ、main のいずれから到達するかに応じて順位付け
test_coverage	テストカバレッジのないファイル
architecture	アーキテクチャ上の問題 — 巨大モジュール、循環依存、孤立した領域
crossref	ファイルをまたぐシンボル参照
type_drift	モジュール間の型シグネチャの不一致
db_schema	マイグレーションで作成されるがコード内で名前が参照されないテーブル、およびマイグレーションで作成されない SQL ORM モデル
migration_parity	スキーマ変更に対応するマイグレーションの不足
manifest_compliance	package.json／Cargo.toml／go.mod の準拠に関する問題
literal_scan	ハードコードされた URL、IP、ポート、絶対パス、TODO
coupling	モジュール結合度の指標
cycles	循環依存の検出
duplication	再実装されたフリー関数 — 同じ処理が二度書かれている箇所
clones	名前と空白を無視して、コピー＆ペーストされた関数本体を検出
spawn_scan	ファイルをまたいで、ループまたはタイマー内で起動されるインタープリターを検出。起動コストと起動頻度の積で順位付け
deps	依存関係の一覧 — 重複するバージョン、参照されていないクレート、使用箇所が 1 か所だけのクレート
leak_shapes	メモリリークのパターンと、それぞれを判定するランタイム系列
logic_shapes	デプロイ単位のメモリ上限に対する固定バイト定数、およびレプリカ数 × プールサイズとコネクションプーラーの接続容量との比較
call_cost	呼び出しグラフをたどって、各要素にかかるデータベースおよび HTTP の往復回数に基づき順位付けした、行を反復処理するループ
field_contention	2 つ以上の所有者が書き込む、宣言済み状態のフィールド
health	上記の解析結果を集約した、単一のインデックス健全性レポート

対応言語

tree-sitter を介して 40 以上の言語に対応：Rust、Python、TypeScript/TSX、Go、Zig、C、C++、Java、Ruby、Bash、C#、Kotlin、Lua、Scala、Elixir、R、Swift、Dart、Haskell、TOML、JSON、YAML、HTML、CSS、SCSS、SQL、HCL、Dockerfile、Markdown、Nix、Make など。

設定

codeindex --mcp                          # Run as MCP server (stdio)
codeindex --mcp --no-daemon              # ...without sharing the workspace daemon
codeindex --daemon-idle-secs 0           # Keep the daemon resident indefinitely
codeindex --workspace ./my-project       # Index a specific directory
codeindex --project-id my-project        # Project identifier
codeindex -v                             # Print version
codeindex -h                             # Print help

# Environment variables
CODEINDEX_WORKSPACE=/path/to/project     # Same as --workspace
CODEINDEX_PROJECT_ID=my-project          # Same as --project-id

利用を促す

エージェントにいつ使えばよいかを伝えずに登録するサーバーは使われずにとどまり、呼び出しがどれほど安価でも、使われないインデックスには何の価値もありません。このプラグインは、効果が現れる順に次の3つを提供します。

1. SessionStart のブリーフィング。 セッションごとに1回、約240トークンで、ソースファイルがあるリポジトリでは codeindex が利用可能であり、コードに関する質問の種類ごとに使うツールを伝えます。エージェントがツールを選ぶ前に表示されるため、最初の選択を変えられる唯一のタイミングです。
2. PreToolUse のヒント。 セッション中のコードに関する質問が1回目、8回目、25回目のときに発動します。インデックスのほうが適切に回答できる質問をスキャンで処理しようとしている場合、その質問に合ったツールを示します。Bash に加えて Read／Grep／Glob にも対応します。ファイル操作をシェル経由にする権限モードでは、実際のスキャンの大半がそこで行われるためです。
3. スキル。 モデルがタスクに必要だと判断したときに読み込みます。

助言は習慣には勝てません。そのため、インデックスが明らかに優れている限定的なケース、つまり、以前にインデックス化されたプロジェクトで、コマンドライン全体が識別子検索になっている場合は、説得するのではなく拒否します。ただし、ファイルの読み取りは決して拒否しません。Edit の前にバイト列が必要なためです。ビルドやテストも行う行は拒否せず、セッション中に3回拒否したら以降は拒否を停止するため、セッションを進行できなくなる原因にはなりません。

これはデフォルトで有効で、オフにするにはスイッチを1つ切り替えるだけです。手動で編集するファイルはありません。プラグインのオプションなので、/plugin には「インデックスのほうが適切に回答できるスキャンを拒否する」と表示され、Claude Code が選択内容をフックに渡します。プラグインを使わない場合や、単一のセッションだけで設定する場合は、環境変数の CODEINDEX_ENFORCE=0 でオプションを上書きし、CODEINDEX_ENFORCE=1 で再度有効にできます。

効果を決めつけずに測定しましょう。python3 plugin/measure_routing.py を実行すると、マシン上にあるすべての Claude Code ホームを対象に、セッションごとにコードに関する質問のうちスキャンに回った数とインデックスに回った数を数えます。

インデックス化されるツリー

--mcp モードでは、作業ディレクトリはユーザーではなくクライアントに属し、対象プロジェクトではないことがよくあります。Claude Code はプラグインの MCP サーバーをプラグイン自体のディレクトリから、ユーザースコープのサーバーを設定ディレクトリから起動するためです。そのため、ワークスペースは次の順で解決され、最初に得られた有効な結果が採用されます。

1. --workspace または CODEINDEX_WORKSPACE。明示的に指定された結果が上書きされることはありません。
2. CLAUDE_PROJECT_DIR。Claude Code は起動するすべての MCP サーバーにこの値を設定します。
3. 起動ディレクトリから上位へたどり、.git、package.json、Cargo.toml、go.mod、build.zig、pyproject.toml のいずれかを目印として探します。
4. クライアントの MCP roots。上記のルートが推測によるものだった場合、サーバーはハンドシェイク時にルートを問い合わせます。推測したルートが拒否された場合、またはクライアントが報告するすべてのルートの外にある場合は、その中からルートを採用します。notifications/roots/list_changed にも対応しているため、--add-dir で追加したディレクトリを使ってセッションを引き続き利用できます。

status は有効なルートを workspace として、ファイルウォッチャーが実行中かどうかを watcher として報告します。結果が空に見える場合は、これらを確認してください。間違ったツリーのインデックスでも、正しいツリーのインデックスと同じくらい確信をもって、あらゆる質問に回答してしまいます。

ホームディレクトリ全体、ファイルシステムのルート、または複数の独立したリポジトリを含むだけのフォルダーはインデックス化しません。ワークスペースが拒否された場合、クエリにはすべて、その理由と修正に使う1回の呼び出し、つまりプロジェクトのパスを指定した index_workspace を返します。「結果なし」とは返しません。

アーキテクチャ

• パーサー：40 以上の文法を備えた tree-sitter を単一のバイナリにコンパイルします
• インデックス：あいまいなテキスト検索用のトライグラムインデックスと、識別子を正確に検索するための転置単語インデックス
• 依存関係グラフ：ファイルレベルのインポート解決と、順方向および逆方向のエッジ
• バージョンストア：ファイルの変更をシーケンス番号で追跡し、増分更新を可能にします
• ライブウォッチャー：ファイルの作成／変更／削除時に再インデックス化します（MCP モードではバックグラウンドスレッド）。Linux では inotify を使用し、macOS と Windows では数秒ごとに mtime とサイズを比較するポーリング走査を行います。status は、現在稼働中のバックエンドを watcher_backend として報告します。
• スナップショット：完全なインデックスを .codeindex.json に保存するため、再起動時には再インデックス化せずにスナップショットを読み込みます
• MCP サーバー：stdio 経由の JSON-RPC で、MCP 2024-11-05 プロトコルを実装しています
• ワークスペースデーモン：リポジトリで最初に起動したセッションがバックグラウンド デーモンを起動してそこへのリレーとなり、以降のセッションは接続するだけです。Linux、 macOS、Windows 10 1803 以降では、$XDG_RUNTIME_DIR/codeindex （または TMPDIR 内のユーザーごとのディレクトリ）に Unix ドメイン ソケットを作成します。ソケット名はワークスペースとバイナリのバージョンのハッシュで 決まるため、再ビルドしたバイナリが以前のバージョンのデーモンを引き継ぐことは ありません。セッションが接続されていない状態が 15 分続くと終了します。問題が 発生した場合は、すべてインプロセスでのインデックス化にフォールバックします。これは デーモン導入前の動作です。--no-daemon で無効にできます。

プラットフォームのサポート

特記がある場合を除き、すべての行のビルドは CI で行われ、そのプラットフォーム上でテストが実行されます。status は現在稼働中のウォッチャーバックエンドを報告するため、推測する必要はありません。

	バイナリ	CI でテストを実行	ウォッチャー	install.sh	プラグイン
Linux x86_64	はい	はい	inotify	はい	はい
Linux aarch64	はい	クロスコンパイル	inotify	はい	はい
macOS aarch64	はい	はい	ポーリング	はい	はい
macOS x86_64	はい	クロスコンパイル	ポーリング	はい	はい
Windows x86_64	はい	はい	ポーリング	シェルが必要	下記参照
Windows aarch64	はい	クロスコンパイル	ポーリング	シェルが必要	下記参照

Windows では、install.sh とプラグインのランチャーはシェルスクリプトのため、 Git Bash、MSYS2、または Cygwin が必要です。これらは環境を検出し、適切な .exe アセットを解決します。プラグインはこのランチャーを通じてサーバーを登録するため、 シェルのないネイティブ Windows 版 Claude Code では、バイナリを直接登録してください。

claude mcp add -s user codeindex -- C:\path\to\codeindex.exe --mcp

ここに署名や公証がされたものはありません。macOS では、curl で取得したバイナリは Gatekeeper の警告なしに実行できます。ブラウザーからダウンロードしたものは 隔離されるため、xattr -d com.apple.quarantine codeindex で解除できます。

ソースからのビルド

Zig 0.16.0 が必要です。

cd zig
./fetch-vendor.sh    # Clone tree-sitter + 40 grammar repos
zig build -Doptimize=ReleaseFast
# Binary: zig/zig-out/bin/codeindex

テストを実行します。

cd zig && zig build test-bin && ./zig-out/bin/test

zig build test は、ビルドランナーの IPC プロトコルを通じて stdout に結果を出力しますが、 リンクされた tree-sitter の C ソースがデバッグ用の printf 経路を通じてこれを破損します。 テスト用バイナリをビルドして直接実行すれば、プロトコルに妨げられることなく同じテストを 実行できます。

比較

	codeindex	ast-grep	ctags	LSIF	Sourcegraph
MCP ネイティブ	はい	いいえ	いいえ	いいえ	いいえ
トークン効率	はい（ファイル全体ではなくアウトライン）	いいえ	一部対応	はい	はい
単一バイナリ	はい	はい	はい	いいえ	いいえ（サーバー）
ライブウォッチャー	はい（inotify／ポーリング）	いいえ	いいえ	いいえ	いいえ
依存関係グラフ	はい	いいえ	いいえ	はい	はい
影響範囲	はい（推移的）	いいえ	いいえ	いいえ	一部対応
リファクタリングプランナー	はい（plan_change）	いいえ	いいえ	いいえ	いいえ
言語	40 以上	20 以上	50 以上	さまざま	さまざま

chat-recall と連携

codeindex は、目の前にあるコードについての質問に答えます。chat-recall は、すでに行った作業についての質問に答えます。Claude Code、Gemini CLI、Codex、OpenCode、Antigravity、Cursor のセッションをインデックス化し、検索可能な履歴にまとめ、それを MCP 経由でも公開します。

両者を組み合わせることで、エージェントが忘れてしまうことの両面をカバーできます。codeindex は、概要を把握できるファイルを読み直すのを防ぎ、chat-recall は、すでに完了した作業をやり直すのを防ぎます。chat-recall は PATH 上に codeindex のバイナリがあるかを検出し、見つかった場合はコードインテリジェンス用のツールを4つ追加で登録します。どちらも、もう一方を必要としません。

ライセンス

MIT。詳細は LICENSE をご覧ください。