Claude Codeで大きなコードベースを扱うと、エージェントは「このモジュールはどこで定義されている?」のたびにgrep・glob・Readを連打し、コールパスを手作業で組み直し、本題に入る前に予算の多くを探索で使う。CodeGraphは、ソースをtree-sitterでAST解析してシンボルと関係をローカルのSQLiteに格納し、エージェントがそのグラフをMCPサーバー経由で1回クエリするだけで済むようにする。下は公式READMEに載る codegraph init のデモだ。

codegraph init を実行し、tree-sitterでコードベースを解析してローカルの知識グラフを構築していくCLIデモ
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ソース)・コールパス(動的ディスパッチ含む)・影響半径をまとめて返す。

CodeGraphなしのgrep探索の往復と、codegraph_explore 1コールで関連ソース・コールパス・影響半径をまとめて返す比較図
従来のgrep/Read往復(左)と、codegraph_explore 1コール(右)の違い。図はREADMEの「Why CodeGraph」記述を要約したもの。

効く理由はコード構造の安定性にある。誰が誰を呼ぶか、どのクラスがどのインターフェースを実装しているかは、ファイル内容よりはるかに変わりにくい。

INDEX ONCE, ASK ONCEグラフができるまで

一度パースして保存し、エージェントは1回のexploreで答える

  1. tree-sitter

    ASTからシンボルと呼び出し・継承・インポートを抽出

  2. SQLite

    node:sqlite・WAL・FTS5

  3. 参照解決

    呼び出しを定義へ。言語境界も

  4. codegraph_explore

    本文+コールパス+影響半径

変更は OS のファイル監視で検知し、約2秒のデバウンス後に差分だけ再インデックス。出典: colbymchenry/codegraph README

抽出の段階でフレームワーク固有のパターン(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レポすべて

出典: README のベンチマーク(2026-08-05再測定・claude-opus-4-8・7コードベース・各4回の中央値)
コードベース 言語・規模 ツールコール 時間 ファイル読込 トークン コスト
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
  • 密なペイロードが窓に居座る

支点はセッションの長さと、コンテキスト窓の大きさ

出典: README と docs/benchmarks/residual-context-occupancy.md(2026-08-05公表)

導入前に知っておきたい副作用

  • ・ベンチマークが測っているのはスループットで、コンテキスト窓の残量ではない。後者の軸では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

参照ソース