Claude Codeで大きなコードベースを扱うと、エージェントは「このモジュールはどこで定義されている?」のたびにgrep・glob・Readを連打し、コールパスを手作業で組み直し、本題に入る前に予算の多くを探索で使う。CodeGraphは、ソースをtree-sitterでAST解析してシンボルと関係をローカルのSQLiteに格納し、エージェントがそのグラフをMCPサーバー経由で1回クエリするだけで済むようにする。下は公式READMEに載る codegraph init のデモだ。
codegraph init の実行デモ。1コマンドで .codegraph/ を作り、全ソースをAST解析してグラフを構築する(出典: colbymchenry/codegraph README)30秒でわかるCodeGraph
- ・Claude Code・Cursor・Codex・Geminiなど8種に対応するローカル知識グラフMCPサーバー。MIT・★68,689(2026-08-31)・v1.5.0
- ・公式が2026-08-05に測り直した値は、7コードベースでツールコール88%減・53%高速化・トークン62%減・コスト44%減・ファイル読込は7レポとも0件
- ・旧値「58%減・22%速」は対照群が汚染された条件の数字で、公式自身が差し替えた
- ・副作用:セッション終了時に窓へ残る取得コンテキストは約80%増える(VS Codeで67k vs 18k)
- ・MCPは単一ツール
codegraph_explore。curl一発で入り、Node.js不要
Claude Code全体の使い方は Claude Code|2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き をご覧ください。
CodeGraphとは:探索を1クエリに畳むローカル知識グラフ
従来のエージェントは、grep/globでファイルを見つけ、Readで開き、別のファイルへ飛び、また読む。このループが大きなリポジトリほど膨らみ、しかもgrepは動的ディスパッチ(インターフェース→実装、コールバック、Reactの再レンダリング等)を追えないので、コールパスは推測で埋めることになる。CodeGraphは「エージェントに渡す地図を事前に作る」。「認証はどう処理される?」と聞かれたら、1回の codegraph_explore で、関連シンボルの本文(ファイル別のverbatimソース)・コールパス(動的ディスパッチ含む)・影響半径をまとめて返す。

効く理由はコード構造の安定性にある。誰が誰を呼ぶか、どのクラスがどのインターフェースを実装しているかは、ファイル内容よりはるかに変わりにくい。
INDEX ONCE, ASK ONCEグラフができるまで
一度パースして保存し、エージェントは1回のexploreで答える
-
tree-sitter
ASTからシンボルと呼び出し・継承・インポートを抽出
-
SQLite
node:sqlite・WAL・FTS5
-
参照解決
呼び出しを定義へ。言語境界も
-
codegraph_explore
本文+コールパス+影響半径
抽出の段階でフレームワーク固有のパターン(Djangoの path()、FastAPIの @app.get() 等)も拾い、参照解決ではDjango CBVの .as_view() やiOS/React Nativeのブリッジのような間接参照も繋ぐ。変更はOSのファイルイベント(macOSはFSEvents、Linuxはinotify、WindowsはReadDirectoryChangesW)で検知し、約2秒のデバウンス後に差分だけを再インデックスする(CODEGRAPH_WATCH_DEBOUNCE_MS で調整可)。未反映のファイルを含む回答には ⚠️ バナーが付き、「そのファイルは直接Readして」と指示される。MCPサーバー再接続時は (サイズ・mtime)+内容ハッシュで作業ツリーと照合するので、別エディタや git pull の変更も次の初回クエリで吸収される。
| 項目 | 内容 |
|---|---|
| ライセンス / 版 | MIT / v1.5.0(2026-07-21) |
| GitHub | ★68,689(2026-08-31)、Fork 4,088(2026-08-06) |
| 実装 | TypeScript+Rustパースカーネル(v1.5.0で導入) |
| 対応エージェント | Claude Code・Cursor・Codex CLI・opencode・Hermes Agent・Gemini CLI・Antigravity IDE・Kiro |
| ストレージ | SQLite(node:sqlite・WALモード・FTS5全文検索) |
| 対応言語 / ルート検出 | 30言語以上 / 17フレームワーク |
| Node.js / クラウド送信 | 不要(ランタイム同梱)/ なし(完全ローカル) |
CodeGraphのインストールと使い方
「CLIを入れる」「エージェントに配線する」「プロジェクトをインデックスする」は別々の操作だ。インストーラー(codegraph install)はコードをインデックスしないので、グラフはプロジェクトごとに codegraph init で作る。
# 1. CLI(macOS / Linux。Node.js不要)
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Windows(PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
# Node.jsがあれば npm でも可
npm i -g @colbymchenry/codegraph
# 2. 新しいターミナルで、エージェントへ配線(npx @colbymchenry/codegraph で1と2を一気に)
codegraph install
# 3. エージェントを再起動し、対象プロジェクトで初期化
cd your-project
codegraph init # .codegraph/ を作成し、フルインデックスまで構築
インストーラーは codegraph をPATHに置くが現在のシェルは書き換えないので、2の前に新しいターミナルを開く。codegraph install は8種のエージェントを自動検出し、MCP設定をグローバルかローカルに書き、指示ファイル(CLAUDE.md/AGENTS.md/GEMINI.md)にマーカー付きの小さなCodeGraphセクションを足し、Claude Codeなら自動許可も設定する。CIでは codegraph install --yes、--target=cursor,claude、--location=local、--print-config codex が使える。アップグレードは codegraph upgrade(--check で確認、バージョン指定でピン留め)。
手動で設定するなら ~/.claude.json に次を足し、~/.claude/settings.json に "mcp__codegraph__*" を1つ加える。MCP設定の詳細は MCPサーバーの作り方2026年完全ガイド も参照されたい。
{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "--mcp"]
}
}
}
MCPを使わずCLIから叩くこともできる(explore/node はMCPツールと同じ出力)。
codegraph explore <query> # 関連ソース+コールパスを一括取得
codegraph node <symbol|file> # 1シンボルの本文+呼び出し元を行番号付きで
codegraph query <search> # シンボル検索(--kind / --limit / --json)
codegraph callers|callees <symbol>
codegraph impact <symbol> # 変更の影響範囲(--depth)
codegraph files [path] # ファイル構造
codegraph index|sync|status|unlock [path]
codegraph uninit [path] / uninstall
codegraph telemetry [on|off] # 匿名利用統計(コード・パス・シンボル名は送られない)
# 変更ファイルが影響するテストだけを走らせる
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
npx vitest run $AFFECTED
fi
codegraph affected はインポート依存を推移的にたどり(--depth 既定5、--filter でテストのglob、--json)、大規模モノレポのCI時間を削れる。
CodeGraphのベンチマーク:2026-08-05の再測定で88%減
READMEは7つの実コードベースで、Claude Opus 4.8(claude-opus-4-8)を claude -p のheadlessで動かし、同じアーキテクチャ質問をWITH(MCP有効) と WITHOUT(空のMCP設定) で各4回測った中央値を公開している。どちらもReadやGrepは使える状態で、差は「知識グラフを直接引く経路」があるかどうかだ。
RE-MEASURED公式の再測定
対照群のCLI経路を塞いで測り直すと、ツールコール88%減
88%減
ツールコール
旧値は58%減(汚染条件)
53%速
回答までの時間
旧値は22%速
0件
ファイル読み込み
7レポすべて
| コードベース | 言語・規模 | ツールコール | 時間 | ファイル読込 | トークン | コスト |
|---|---|---|---|---|---|---|
| VS Code | TypeScript・約11kファイル | 2 vs 28 | 2.2倍速(58秒 vs 2分10秒) | 0 vs 12 | 77%減 | 71%安 |
| Excalidraw | TypeScript・約640 | 2 vs 43 | 3.6倍速(45秒 vs 2分42秒) | 0 vs 18 | 84%減 | 78%安 |
| Django | Python・約3k | 3 vs 14 | 35%速(54秒 vs 1分23秒) | 0 vs 8.5 | 41%減 | 13%安 |
| Tokio | Rust・約790 | 3 vs 29 | 2.6倍速(1分3秒 vs 2分43秒) | 0 vs 19 | 65%減 | 64%安 |
| OkHttp | Java・約645 | 1 vs 6 | 43%速(33秒 vs 58秒) | 0 vs 2 | 54%減 | 21%安 |
| Gin | Go・約110 | 1 vs 7 | 39%速(28秒 vs 46秒) | 0 vs 4 | 52%減 | ほぼ同等 |
| Alamofire | Swift・約110 | 4 vs 33 | 2.6倍速(54秒 vs 2分22秒) | 0 vs 16.5 | 59%減 | 57%安 |
| 全体 | 全レポ | 88%減 | 53%速 | 7レポとも0 | 62%減 | 44%安 |
旧値が差し替わったのは、MCPを無効にしても codegraph CLIがPATH上に残っていたからだ。READMEによれば、ブロックしないハーネスでは28回中26回、WITHOUT側がCLIを見つけて使っていた。CLI呼び出しはツールコールに数えられず出力だけがコンテキストに入るので、比較は両方向に歪む。再測定ではPATHをサニタイズし、PreToolUse フックでCLIのBash実行を拒否して、WITHOUT側28回すべての到達をブロックした。差が58%→88%に広がったのは、比較対象がこれまで下駄を履いていたからだ。
再現性が最も高いのはファイル読み込みで、WITH側は7レポすべて0件、WITHOUT側は2〜19ファイル。コストの効き幅はリポジトリの規模ではなく、質問が要求した探索量で決まる。28〜43ツールコールを要した質問(VS Code・Excalidraw・Tokio・Alamofire)は57〜78%減、14コールのDjangoは13%減、7コールのGinはほぼ同等。640ファイルのExcalidrawが78%安で3,000ファイルのDjangoが13%安という逆転が、その証拠になる。Opus 4.8での値が旧Opus 4.7時代より低く出たのは、4.8がメインスレッドでgrep/Readを効率よく使い、no-CodeGraph側のベースラインが強くなったためだとREADMEは説明している。
THROUGHPUT VS WINDOW副作用
処理するトークンは減り、窓に残る文脈は増える
減るもの
- ツールコール 88%減
- トークン 62%減
- コスト 44%減
増えるもの
- 残る取得コンテキスト 約80%増
- VS Code で 67k vs 18k
- 密なペイロードが窓に居座る
支点はセッションの長さと、コンテキスト窓の大きさ
導入前に知っておきたい副作用
- ・ベンチマークが測っているのはスループットで、コンテキスト窓の残量ではない。後者の軸ではCodeGraphのほうが重い
- ・同じ7レポのマルチターンセッションで、終了時に残る取得コンテキストはファイル読み込み型より約80%多い(VS Codeで67,000 vs 18,000トークン)。1回で答えきる密なペイロードが窓に居座り、grep型の小さな結果は押し出されて消えるため
- ・短〜中距離のタスクではCodeGraph有利。小さい窓で長時間回すなら残留を予算に見込む。レポ別の値は
docs/benchmarks/residual-context-occupancy.md
MCPインターフェースと対応言語
MCPが公開するのは単一の codegraph_explore だ。1.0で「細かいツールを並べるより、強力な1ツールのほうがエージェントが誤選択せず、毎セッションの文脈も節約できる」という計測に基づいて集約された。ファイル名やシンボル名を書けば、その現在のソースを行番号付きで読める(Readと同じ形)。旧来の codegraph_node・search・callers・callees・impact・files・status は機能としては健在だがデフォルト非公開で、CODEGRAPH_MCP_TOOLS=explore,node,search,callers のように再公開できる。.codegraph/ の無いルートでも projectPath を渡せば別プロジェクトを同一セッションで問い合わせられ、インデックスの無いパスは「ビルトインツールを使え」と返すだけで失敗しない。
initialize 応答では、「構造的な質問はCodeGraphで直接答えよ。返ったソースは既読として扱い、grepで再検証するな。編集後はstalenessバナーを確認せよ」と伝える。CodeGraphは直接クエリされたときだけ効くので、探索をファイル読みのサブエージェントに委任させない。ハーネスエンジニアリングの「メインはオーケストレーションに専念」と一見逆だが、1コールで済むならメインで完結させるのが正解になる。
| 区分 | 言語 |
|---|---|
| フル対応 | TypeScript / JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C / C++、Swift、Kotlin、Dart、Liquid、Pascal・Delphi(DFM/FMXフォーム含む) |
| 特記つき | Objective-C(部分対応)、Scala(Scala 3 enum)、Svelte(runes・SvelteKit)、Vue(script-setup・Nuxt)、Astro、R(S4/R5/R6)、Lua / Luau(Roblox require) |
| v1.3.0追加 | Nix、ArkTS(HarmonyOS)、Terraform/OpenTofu、CUDA(ホスト→カーネル呼び出し)、Solidity、Erlang(OTP)、Visual Basic .NET、COBOL(PERFORM/CALL/CICS)、CFML |
ルート検出は17フレームワーク(Django・Flask・FastAPI・Express・NestJS・Laravel・Rails・Spring・Play・Drupal・Gin/chi/mux・Axum/actix/Rocket・ASP.NET・Vapor・React Router・SvelteKit・Vue Router/Nuxt・Astro など)で、/api/users を変えたときに影響するハンドラーが1回で分かる。混在iOS/RNコードでは、Swift↔ObjC、RNのレガシーブリッジ(RCT_EXPORT_METHOD/@ReactMethod)、TurboModules、Expo Modules、Fabric/Paperビューまで言語境界を越えて繋ぎ、各エッジに provenance:'heuristic' と synthesizedBy(例:swift-objc-bridge)が付く。
v1.5.0までの更新・除外ルール・他ツールとの比較
| バージョン | 日付 | 変わったこと |
|---|---|---|
| v1.5.0 | 2026-07-21 | パースをネイティブRustカーネルへ。保存→グラフ反映が1秒未満(27,000ファイル規模でも) |
| v1.4.0 | 2026-07-10 | HDD・ネットワークフォルダ・仮想ディスクでのインデックスを改善 |
| v1.3.0 | 2026-07-07 | 9言語を追加 |
| v1.2.0 | 2026-07-02 | ローカル変数の型推論を12言語へ。const logger = new Logger(); logger.log() を追える |
v1.5.0のリリースノートは「プロジェクト史上最大の性能アップグレード」とし、Swiftコンパイラ(27,000ファイル)で3分超→約100秒、Linuxカーネル(70,000ファイル・2コア6GB)で26分→12分未満と公表している。生成グラフは従来エンジンとバイト単位で一致を確認済みで、プリビルドの無い環境や構文エラーのファイルは従来エンジンに自動で戻る。グラフ形式は互換なので通常は再インデックス不要。低速ディスクでは CODEGRAPH_NO_WAL_DEFER=1 や CODEGRAPH_PARSE_TIMEOUT_MS で調整できる。
1.0からは node_modules・vendor・dist・build・target・.venv・Pods・.next などを.gitignoreが無くても標準で除外し、.gitignore 記載パスと1MB超のファイルも外す。取り込みたいときは .gitignore に !vendor/、コミット済みのディレクトリを外すなら codegraph.json の exclude、非標準拡張子は extensions でマッピングする。
| ツール | アプローチ | 削減対象 | 対応エージェント |
|---|---|---|---|
| CodeGraph | ローカル知識グラフ(MCP) | 探索ツールコール・ファイル読込 | 8種 |
| RTK | 出力フィルタリング(プロキシ) | Claude Codeの出力冗長性 | Claude Code専用 |
| Token Savior | MCPサーバー(シンボルナビ) | ファイル読み込み操作 | 汎用MCP |
| claude-token-efficient | CLAUDE.mdルール | 出力フォーマット冗長性 | Claude Code専用 |
| Token Optimizer MCP | 圧縮+SQLiteキャッシュ | テキスト転送コスト | 汎用MCP |
Claude Codeトークン最適化ツールの中では「探索層の根本解決」にあたり、異なるエージェントを使うチームでも .codegraph/ を共有できる。RTKとはアプローチが違うので併用できる。一方、小規模リポジトリ(100〜200ファイル未満)ではトークン・コストの効果が薄く(速度は出る)、初期インデックスに数秒〜数分かかり、「コードを書く」ツールコールは減らない。
トラブルシューティング
| 症状 | 原因と対処 |
|---|---|
| “CodeGraph not initialized” | 対象プロジェクトで codegraph init を実行していない |
| インデックスが遅い | コミット済みの巨大ディレクトリが対象になっている。codegraph.json の exclude で外し、--quiet を付ける |
| “database is locked” | pre-0.9の古いインストール(再インストール)か、codegraph status の Journal: が wal 以外。ネットワーク共有やWSL2の /mnt ではWALが効かないので、ローカルディスク(WSLならLinuxの ~/)に移す |
Transport closed(statusは正常) |
ほぼWSL2でWindowsドライブ上のプロジェクト。なお起きるなら CODEGRAPH_NO_DAEMON=1 をMCPサーバー環境に設定 |
| シンボルが見つからない | 保存後約2秒で同期(codegraph sync で手動も可)。拡張子が対応言語か、除外対象でないかを codegraph status で確認 |
コードはクラウドへ送られず、.codegraph/codegraph.db に保存される。匿名の利用統計(使ったコマンド・言語など)はデフォルトで送られるが、codegraph telemetry off で止められる。中〜大規模プロジェクトで毎日Claude Codeを使っているなら、まず速度のために試す価値が高い。
# 今すぐ試す(CLI導入 → 配線 → 初期化)
npx @colbymchenry/codegraph





