codegraph

codegraph

8 個の MCP ツールとして公開されるローカルコードグラフです。O(1) の SQLite 検索と FTS5 検索により探索を高速化し、コードベースの構造を把握するために必要な grep と Read の反復を大幅に削減します。

grep の代替ではありません。Codegraph は呼び出しグラフを tree-sitter で近似したものであり、コンパイラー品質のものではありません。高速でトークン消費は少ない一方、完全ではなく、偽陰性があります。構造の把握とたどり方を加速するツールとして扱い、網羅性の真実の情報源として grep を使い続けてください。以下の完全性と制限を参照してください。この違いは重要であり、脚注ではありません。

使用する場面

• 構造がすぐにはわからない既存のリポジトリ
• タスクに「X はどこで使われているか」「Y を変更すると何が壊れるか」「A から B までの流れを追う」が含まれる場合
• 長時間のセッション。複数のクエリにわたってコールドスタートのコストを回収できる場合

使用しない場面

• 単一ファイルの編集や単純な検索
• セッションがコールドスタートのコストより短くなる可能性が高い場合（リポジトリごとの数値については references/spike.md を参照）
• リポジトリが初期化されておらず、キャッシュされた .codegraph/ もなく、セッションも短い場合

完全性と制限 — 結果を信頼する前にお読みください

Codegraph はコンパイラーではなく tree-sitter を基盤としているため、呼び出し／参照のエッジは近似です。確認済みの 3 つの方法で失敗します。これらから、基本原則が導かれます。

網羅性の真実の情報源は grep です。Codegraph は構造の把握とたどり方を加速するツールです。この関係を逆転させないでください。

非対称性こそが要点です。リファクタリングでは、偽陰性は危険です（呼び出し元を見落とし、壊れた状態でリリースしてしまいます）。偽陽性は単に煩わしいだけです（確認して除外できます）。Codegraph には偽陰性がありますが、grep にはありません。そのため、Codegraph は候補の提示と順位付けに使えますが、網羅的な回答が必要な場合は grep で確認してください。

約 580 ファイルの Rust+TS リポジトリで測定した、3 つの失敗パターンは次のとおりです。

1. 不完全なエッジ → 偽陰性。 callers／callees／impact は、構文だけではレシーバーの型を解決できない場合（ローカル変数、ジェネリクス、トレイトオブジェクトへの呼び出し）、実際の呼び出し箇所を見落とします。測定結果：実際の呼び出し元が 8 件あるメソッドに対し、返されたのは 2 件でした。除外された 5 件は local.method() とジェネリックディスパッチの箇所で、警告はありませんでした。一意な自由関数と直接呼び出しでは正確（1/1、2/2 を確認済み）ですが、メソッドディスパッチでは信頼できません。
2. 名前解決は曖昧で、オーバーロードを区別できません。 名前のみのクエリは前方一致するため、useWorkspace の検索結果に別のシンボルである useWorkspacesQuery が返されます。また、オーバーロードも混同します（19 個の定義がある execute では、トレイトメソッドではなく sqlx の .execute() DB 呼び出しが返されました）。同じ名前に複数の定義がある場合は、特定のシンボル ID を指定して codegraph_node に切り替えてください。名前のみの callers／callees では、どの定義に属するかを特定できません。
3. インデックスの更新はディスクより遅れます。 CLI では codegraph sync が完了するまで（約 0.3 秒）何も表示されません。MCP のファイルウォッチャーを使うと、この遅れは約 1～2 秒に短縮されます。編集直後はインデックスが正しくありません。追いつくまでは grep／Read を正としてください。

判断マトリクス

タスク	ツール	理由
概要を把握する／「サブシステム X を説明する」／最初の調査	codegraph explore	1 回の呼び出しで、順位付けされた原文が得られます。grep と Read を使うより、必要なコンテキストがはるかに少なくて済みます
一意の名前を持つ自由関数の呼び出し元	codegraph callers（信頼して使う）	一意の名前と直接呼び出しについては正確です
シグネチャ変更／名前変更の前に、呼び出し元をすべて見つける	grep を正とする。codegraph は事前の順位付けにのみ使用	codegraph はこの用途では健全ではありません。網羅性を codegraph に依存することはできません
オーバーロードされた名前（execute、lookup、run、new）に関するもの	grep、または特定の ID に対する codegraph node	名前だけを指定した codegraph は、予測できない形で候補を混同したり、解決しきれなかったりします
コア型の影響範囲	codegraph impact --depth 1 で事前に順位付けしてから、grep で確認	デフォルトの深さ 2 ではテスト関数とファイルごとの file エントリーが加わって結果が膨らみ、深さによる順位付けもされません
編集したばかりのコード	grep（または先に codegraph sync を実行）	再インデックスするまでインデックスは古いままです
トレイトディスパッチ／ジェネリックな呼び出し箇所	grep ＋読み込み	どちらも弱点があります。codegraph は何も通知せずに見落としますが、grep なら少なくともテキストを見つけられます

ワークフロー： まず explore で全体像をつかみ、callers／impact で方向性を確認します。ただし、答えの網羅性が必要になった時点（名前変更、「全員を拾えたか？」など）で grep を使って確認し、codegraph と grep の差分は「grep が過剰に拾った」ではなく「codegraph が見落とした」とみなしてください。

前提条件

• PATH に Node 18 以降があること
• プロジェクトに .codegraph/ があること（ない場合は codegraph init を実行してください）
• クラウドセッションの場合：対象リポジトリのコールドスタートコストが references/spike.md で検証済みであること

ファイル

• references/install.md — ローカル／Claude Code Cloud／devcontainer 向けのインストール方法
• references/usage.md — 8 つの MCP ツールの使い分けと、メインセッションとサブエージェントのルール
• references/spike.md — コールドスタートの測定手順。クラウドセッションで codegraph を利用する前に、新しい対象リポジトリごとに 1 回実行してください

既知の連携対象

ローカル環境でコールドスタートを測定済み（Node 22、4 コア）。クラウドでのコールドスタートは未測定です。クラウドセッションでこれらの数値を利用する前に、references/spike.md を再実行してください。

リポジトリ	インデックス済みファイル	ノード／エッジ	DB サイズ	コールド初期化＋インデックス作成	クエリ所要時間
onsager-ai/onsager	578（rust + tsx/ts）	8.6k / 20k	24 MB	12s	~0.9s
crawlab-team/crawlab	644（go）	6.8k / 15k	11 MB	6s	~0.9s
codervisor/leanspec	695（tsx/rust/ts）	8.9k / 21k	23 MB	10s	~0.9s

クエリごとの所要時間の大部分は Node の起動時間です。SQLite の処理自体はミリ秒単位です。この規模のリポジトリでは、1 回限りの npx install を含むエンドツーエンドのコールドスタートは約 13～19 秒です。