この記事のポイント
  • CodeGraphはClaude Code・Cursor・Codex・Gemini対応のローカル知識グラフMCPサーバー(MIT・65,039星、2026年1月公開から半年でv1.5.0に到達)
  • 公式が2026-08-05にベンチマークを測り直した。7コードベースでツールコール88%減・53%高速化・トークン62%減・コスト44%減・ファイル読込は7レポとも0件
  • 旧値「58%減・22%速」は対照群が汚染された条件の数字だった。CLIをPATHから外しPreToolUseで塞いだ再測定で28/28件の到達を阻止して測り直されている
  • 副作用がある:削減されるのは「処理した」トークンで、セッション終了時に残っている取得コンテキストは約80%増える(VS Codeで67k vs 18k)。狭い窓で長時間回す人は要注意
  • MCPは単一ツール`codegraph_explore`を公開。1コールで関連ソース+コールパス+影響半径を返す
  • curl一発インストール(Node.js不要)、8種のエージェント設定を自動書き換え。30言語超・17フレームワーク対応でゼロコンフィグ

Claude Codeで大規模なコードベースを扱うとき、見えないコストが積み上がっていく。「このモジュールはどこで定義されている?」——そのたびにエージェントはgrep・glob・Readを連打し、ファイルを読み漁り、コールパスを手作業で組み直し、トークンとツールコールを消費し続ける。本題のコードを読む前に、探索だけで予算の大半を使い果たすことも珍しくない。

CodeGraphはこの問題の根本を狙う。ソースコードをtree-sitterでAST解析し、すべてのシンボル・関数呼び出し・クラス継承・インポート関係をローカルのSQLiteデータベースに格納する。Claude Code(とCursor・Codex・Gemini・opencodeほか)はそのグラフをMCPサーバー経由で1回クエリするだけでよく、ファイルを1つずつ開く必要がなくなる。下は公式READMEに掲載されたcodegraph initの実行デモだ。まず「動くところ」を見てほしい。

codegraph init を実行し、tree-sitterでコードベースを解析してローカルの知識グラフを構築していくCLIデモ
codegraph init の実行デモ。1コマンドで .codegraph/ を作り、全ソースをAST解析してグラフを構築する(出典: colbymchenry/codegraph README

2026年1月18日に公開されてから約半年、GitHubスター数は65,039(2026-08-06時点)に達し、最新リリースはv1.5.0(2026年7月21日)だ。実コードベース7種類のベンチマークは2026-08-05に測り直されており、CodeGraphなしと比べてツールコール88%削減・53%高速化・トークン62%削減・コスト44%削減・ファイル読み込みは7レポとも0件という値になっている。

この記事が以前載せていた「58%削減・22%高速化」は、対照群が汚染された条件で測られた古い数字だ。詳しくは後述するが、公式自身がそれを認めて測定をやり直している。さらに、削減されるのは「処理した」トークンであって、セッションに残る文脈はむしろ増えるという副作用も同時に公表された。数字を使う前に、この2点は押さえておきたい。

Claude Code全体の使い方は Claude Code完全ガイド2026:インストールから本番運用まで をご覧ください。

CodeGraphとは——ローカル知識グラフがエージェントを変える

CodeGraphの設計思想は「エージェントに渡す地図を事前に作る」ことだ。何ができるかを一言でいえば、コードベース全体の「シンボルとその関係」を事前にインデックス化し、エージェントの探索を1クエリに畳み込むツールである。

AIコーディングエージェントがコードを探索する従来の方法はこうだ。まずgrep/globでファイルを見つけ、Readでファイルを開き、内容を確認し、別のファイルへジャンプし、また読む……この探索ループがトークンとツールコールを消費する。大きなリポジトリほどこのコストは爆発的に増える。しかもgrepは動的ディスパッチ(インターフェース→実装、コールバック、Reactの再レンダリング等)を追えないため、コールパスは結局エージェントの推測で埋めることになる。

CodeGraphはこのループを断ち切る。インデックス構築時に一度だけソースコードをパースし、シンボル(関数・クラス・メソッド・変数)とエッジ(呼び出し・継承・インポート)をSQLiteに保存する。エージェントが「認証はどう処理される?」と要求すると、CodeGraphは1回のcodegraph_exploreで、関連シンボルの本文(ファイル別にまとめたverbatimソース)・それらの間のコールパス(grepが追えない動的ディスパッチ含む)・変更したときの影響半径をまとめて返す。ファイルを1つずつ開く必要がない。

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

このアプローチが有効な理由はコード構造の安定性にある。コードの意味的な構造——誰が誰を呼ぶか、どのクラスがどのインターフェースを実装しているか——はファイル内容そのものよりはるかに変化が少ない。1回インデックスを構築すれば、OS File Watcher(macOSではFSEvents、Linuxではinotify、WindowsではReadDirectoryChangesW)が差分を自動同期してくれるため、再インデックスの手間もない。

主要スペック

項目 内容
ライセンス MIT
バージョン(npm) v1.5.0(2026-07-21)
GitHub Stars 65,039(2026-08-06時点)
Forks 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全文検索)
AST解析 tree-sitter
対応言語数 30言語以上(v1.3.0で9言語追加)
フレームワークルート検出 17種
Node.js要件 不要(CLI/MCPはバンドル済みランタイム同梱)
コードのクラウド送信 なし(完全ローカル)

v1.5.0までの更新履歴:Rustエンジンで同期がほぼ即時に

本記事の初出時点は1.0系だったが、2026年7月だけでv1.2.0からv1.5.0まで進んだ。すでに導入済みの人が最も気にする「同期・更新まわり」が集中的に強化されているため、要点を時系列で押さえておく。

バージョン 日付 変わったこと(同期・性能に効くもの)
v1.5.0 2026-07-21 パースエンジンをネイティブRustカーネルへ刷新。保存からグラフ反映が1秒未満
v1.4.0 2026-07-10 低速ストレージ(HDD・ネットワークフォルダ・仮想ディスク)でのインデックスを改善
v1.3.0 2026-07-07 Nix・ArkTS・Terraform/OpenTofu・CUDA・Solidity・Erlang・VB.NET・COBOL・CFMLに対応
v1.2.0 2026-07-02 ローカル変数の型推論を12言語へ拡大。const logger = new Logger(); logger.log() が呼び出し元として追える

v1.5.0の公式リリースノートは、この更新を「プロジェクト史上最大の性能アップグレード」と位置づけている。公表されている実測値は次のとおりだ。

保存→グラフ反映が1秒未満——27,000ファイル規模のリポジトリでも、ファイル保存がほぼ即座にグラフへ届く
Swiftコンパイラのリポジトリ(27,000ファイル・Swift+C++)——リリースサイクル内で3分超から約100秒へ短縮
Linuxカーネル(70,000ファイル)——2コア・6GBのマシンで、26分から12分未満
グラフの同一性を検証済み——Rustカーネルが生成するグラフは従来エンジンとバイト単位で一致することを確認したうえで切り替えている
環境に合わせて自動調整——コンテナ/cgroupを認識した実コア数と実空きメモリからワーカー数を決めるため、非力なVPSでもメモリ枯渇で落ちにくい

プリビルドバイナリが無いプラットフォームや、構文エラーを含む個別ファイルは自動的に従来エンジンへフォールバックする。どちらの経路でも生成されるグラフは同じなので、利用者側で切り替えを意識する必要はない。

更新のしかた
インデックス済みプロジェクトでも、CLIを更新すれば以降の同期は新エンジンで動く。グラフ形式は互換なので、通常は再インデックス不要だ。低速ディスクで挙動を調整したい場合のみ、v1.4.0で追加された CODEGRAPH_NO_WAL_DEFER=1(新しい書き込み方式のオプトアウト)や CODEGRAPH_PARSE_TIMEOUT_MS(1ファイルあたりのパース時間の上限)を使う。

インストール:curl一発から手動設定まで

導入は3ステップに分かれている。「CLIを入れる」「エージェントに配線する」「プロジェクトをインデックスする」は別々の操作であることに注意したい(インストーラーはコードのインデックスまではしない)。

codegraph init を実行してプロジェクトの知識グラフを構築するCLIデモ(再掲)
ステップ3の codegraph init が .codegraph/ を作りグラフを構築する様子(出典: README

ステップ1:CLIをインストール(Node.js不要)

バンドル済みランタイムが同梱されているため、macOS・Linuxではシェルスクリプト経由で直接インストールできる。

# macOS / Linux — Node.js不要、OSに合ったビルドを取得
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

インストーラーはcodegraphをPATHに置くが現在のシェルは書き換えない。次のステップの前に新しいターミナルを開いておく。以後のアップグレードはcodegraph upgrade--checkで更新確認、codegraph upgrade <version>でピン留め)。

ステップ2:エージェントに配線する

新しいターミナルでインストーラーを実行すると、インストール済みのエージェントを自動検出して各エージェントにCodeGraphのMCPサーバーを配線する。

codegraph install
# あるいは1コマンドで一気に:
npx @colbymchenry/codegraph

インストーラーは以下を自動で行う。

・Claude Code・Cursor・Codex CLI・opencode・Hermes Agent・Gemini CLI・Antigravity IDE・Kiroを自動検出
・対象エージェントを選択(複数可)
codegraphをPATHにインストール(エージェントがMCPサーバーを起動できるように)
・設定をグローバル(全プロジェクト共通)またはローカル(プロジェクト固有)に書き込む
・各エージェントのMCP設定と、指示ファイル(CLAUDE.md/AGENTS.md/GEMINI.md)にマーカーで囲まれた小さなCodeGraphセクションを追記(サブエージェントや非MCPハーネスにもcodegraph exploreの使い方を伝えるため)
・Claude Codeが対象の場合、自動許可パーミッションを設定

ここが誤解しやすい:インストーラーはコードをインデックスしない codegraph install(=ステップ2)が行うのはエージェントへの配線だけだ。プロジェクトのグラフはステップ3の codegraph init で別途構築する。グローバルに一度 install すれば全プロジェクトで有効になり、init はプロジェクトごとに1回だけ実行する。

ステップ3:プロジェクトを初期化する

エージェントを再起動してから、対象プロジェクトで初期化する。

cd your-project
codegraph init     # .codegraph/ を作成し、同じステップでフルインデックスまで構築

.codegraph/ディレクトリが作られ、codegraph.dbにインデックスが格納される。以後はAuto-syncがデフォルトで有効になり、ファイル変更のたびにグラフが自動更新される(手動同期は原則不要)。この.codegraph/が存在するプロジェクトで作業するとき、エージェントは自動的にCodeGraphを使うようになる。

非インタラクティブモード(CI・スクリプト向け)

codegraph install --yes                              # エージェント自動検出・グローバル
codegraph install --target=cursor,claude --yes       # 対象エージェントを明示
codegraph install --target=auto --location=local     # プロジェクトローカルに設定
codegraph install --print-config codex               # 設定スニペットを表示するだけ

手動設定:Claude Codeの場合

インストーラーを使わずに手動で設定するには~/.claude.jsonを編集する。自動許可はワイルドカード1つで済む。

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

~/.claude/settings.json"mcp__codegraph__*"を1つ足せば、CodeGraphの全ツールが確認ダイアログなしで通る。MCP設定の詳細は MCPサーバーの作り方2026年完全ガイド も参照されたい。

動作原理:tree-sitter解析からグラフクエリまで

CodeGraphが何を解決するか——エージェントの「探索フェーズ」のコストだ。以下の4段でグラフが構築・維持される。

graph TD A["Claude Code
メインセッション"] -->|codegraph_explore を直接呼ぶ| C["CodeGraph
MCP Server"] C -->|SQLクエリ| D["SQLite DB
codegraph.db"] D -->|シンボル本文+コールパス+影響半径| C C -->|1コールで回答| A E["ソースファイル群"] -->|AST解析| F["tree-sitter
パーサー"] F -->|ノード+エッジ抽出| G["インデックス構築+参照解決"] G -->|格納| D H["OS File Watcher
FSEvents / inotify"] -->|変更検知・2秒デバウンス| G

ステップ1:AST解析と抽出

tree-sitterがソースコードをAST(抽象構文木)に変換する。言語ごとのクエリが関数・クラス・メソッド・変数などのノードと、関数呼び出し・インポート・クラス継承などのエッジを抽出する。この段階でフレームワーク固有のパターン(Djangoのpath()、FastAPIの@app.get()等)も検出される。

ステップ2:SQLite格納とFTS5インデックス

抽出したシンボルとエッジをSQLiteに保存する。FTS5拡張で全文検索が高速に動作する。データベースはNode組み込みのnode:sqliteをWALモードで使うため、MCP経由の並行読み取りが書き込みでブロックされにくい。

ステップ3:参照解決

格納後、関数呼び出しが実際の定義に解決される。login()という呼び出しがどのファイルのどの関数を指しているか、インポートがどのソースに対応しているか、クラス継承の先祖がどこにいるかが紐付けられる。フレームワーク固有の間接参照(Django CBVの.as_view()等)や、後述のiOS/React Nativeブリッジのような言語境界も解決対象に含まれる。

ステップ4:自動同期

MCPサーバーがネイティブOSのファイルイベントを監視する。変更を検知して約2秒のデバウンス後、変更されたソースのみを差分インデックスする(CODEGRAPH_WATCH_DEBOUNCE_MSで調整可能)。デバウンス中に未反映のファイルを参照する回答には⚠️バナーが付き、「そのファイルは直接Readして」とエージェントに指示する仕組みまである。MCPサーバー再接続時には(サイズ・mtime)+内容ハッシュで作業ツリーと照合し、別エディタやgit pullでの変更も次の初回クエリで吸収する。

ベンチマーク:公式が2026-08-05に測り直した7コードベース実測

READMEでは7つの実コードベースを使った詳細なベンチマークが公開されている。測定方法:Claude Opus 4.8(claude-opus-4-8)をclaude -pのheadlessで実行し、同じアーキテクチャ質問をWITH(CodeGraphのMCP有効) vs WITHOUT(空のMCP設定) で各4回測定して中央値を比較。2026-08-05に現行ビルドで測り直されたのが、以下の最新値だ。

重要:どちらもReadやGrepなどのビルトインツールは使用可能な状態で測定されている。 CodeGraphがない場合でも基本ツールは使える。差が出るのは「知識グラフの直接参照」という経路が加わるかどうかだ。

コードベース 言語・規模 ツールコール 時間 ファイル読込 トークン コスト
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%安

旧「58%減・22%速」がなぜ差し替わったのか——対照群が汚染されていた

この記事も以前は「ツールコール58%減・22%高速化」を掲載していたが、その数字はもう使えない理由は測定条件そのものにある。

CodeGraphのMCPサーバーを無効にしても、codegraph CLIバイナリはPATH上に残っている。つまり「CodeGraphなし」のはずのエージェントが、Bash経由でCLIを叩いてCodeGraphに到達できてしまう。READMEはこれを実測で認めており、ブロックしないハーネスでは28回中26回、WITHOUT側のエージェントがPATH上のCLIを見つけて使っていたと書いている。しかもCLI呼び出しは「ツールコール」として集計されず、出力だけがコンテキストに入るため、比較は両方向に歪む

2026-08-05の再測定では、PATHをサニタイズしたうえでPreToolUseフックでCLIのBash実行を拒否し、WITHOUT側28回すべてがCLIに到達を試み、28回すべてブロックされた(汚染0件)ことを明示している。ようやく「本当にCodeGraphなし」の対照群が取れた、というのが今回の再測定の意味だ。差が58%→88%へ広がったのは、CodeGraphが強くなったからというより、比較対象がこれまで下駄を履いていたからである。

7コードベースのツールコール削減率を横棒グラフで示した図。VS Code 81%、Alamofire 58%、Tokio 57%、OkHttp 50%、Gin 44%、Excalidraw 40%
これは差し替え前の旧測定(〜2026-07)のツールコール削減率。CLIをブロックしない条件で測られていたため、現在は上表の値(全レポ平均88%減)に差し替えられている。前後の落差そのものが「対照群の作り方で結果がどれだけ動くか」の実例。

「ファイル読み込みゼロ」がいちばん再現する効果

再測定でも最も安定して現れるのはファイル読み込みの激減だ。表の「ファイル読込」列を見ると、CodeGraphありは7レポすべてで0件、なしでは2〜19ファイル。CodeGraphありのエージェントはcodegraph_exploreが返した本文をそのまま読んで回答に入り、1つもファイルを開かない。一方なしのエージェントは、正しいコードにたどり着く前にfind/ls/grepとReadで予算を使い、最大で43ツールコール・19ファイル読み込みまで膨らむ。

コスト削減の幅を決めるのは「リポジトリの規模」ではなく「探索の量」

旧版のこの記事は「トークン・コスト削減は規模依存」と書いていたが、再測定でこの説明も更新されている。READMEは今回、コストはリポジトリの大きさよりもその質問がどれだけ探索を要求したかを追う、と明言している。

28〜43ツールコールを要した質問(VS Code・Excalidraw・Tokio・Alamofire)→ コスト57〜78%減
14ツールコールで済んだ質問(Django)→ 13%減
7ツールコールで済んだ質問(Gin)→ ほぼ同等

つまり640ファイルのExcalidrawが78%安、3,000ファイルのDjangoが13%安という規模の逆転が起きている。「小さいリポジトリだから効かない」ではなく、「その質問が探索を必要としないなら効かない」が正しい読み方だ。なおどちらのケースでも、WITH側は3コール・1コール・ファイル読み込み0で答えきっている。

コードベースの規模・複雑さが増すほどトークン・コスト削減が大きくなることを示す曲線グラフ
旧READMEが提示していた「規模で効く」モデル。2026-08の再測定では、実際に効き幅を決めるのは規模より質問が要求する探索量だと修正された(出典: README「A note on cost」

落とし穴:削減されるのは「処理した」トークン。残る文脈は約80%増える

導入前に必ず知っておきたい副作用
READMEは同時に、ベンチマークの数字が測っているのは「スループット」であって「コンテキスト窓の残量」ではないと明記した。そしてその軸では、CodeGraphはコストが増える。同じ7レポのマルチターンセッションで、セッション終了時に窓へ残っている取得コンテキストは、ファイル読み込み型エージェントより約80%多い。VS Codeでは 67,000トークン vs 18,000トークンだった。

理由は速さの理由と同じだ。CodeGraphは1回で答えきる密なペイロードを返し、それがそのまま窓に居座る。対してgrep&read型のエージェントは小さな結果を大量に出し入れするので、古いものから押し出されて消えていく。「処理トークンが減る」と「窓に残る量が増える」は同時に成立する——READMEの表現を借りれば、両方が同時に本当だ。

短〜中距離のタスク(1〜数ターンで終わる調査・実装)→ CodeGraph有利。処理トークンもコストも時間も減る
小さい窓で長時間セッションを回す使い方 → 残留コンテキストが効いてくるので、予算を見込んでおく必要がある
・レポ別の実測値は公式リポジトリの docs/benchmarks/residual-context-occupancy.md に開示されている

なお個々の数値は実行ごとに揺れる(中央値4回でならしても裾は残る)。Opus 4.8時代の値が旧Opus 4.7時代より低く出た理由についてもREADMEは説明しており、これはCodeGraphの退化ではなく、Opus 4.8がメインスレッドで効率よくgrep/Readするようになり、no-CodeGraph側のベースラインが強くなったためだ。測定の汚染を自分から開示して測り直し、しかも自分に不利な残留コンテキストの数字まで出す——ベンチマークをこの粒度で開示している姿勢は、数値の信頼性を測るうえで参考になる。

MCPインターフェース:単一ツールcodegraph_explore

CodeGraphのMCPサーバーが公開するのは、いまや単一のツールcodegraph_exploreだ。これは1.0での大きな設計変更で、「メニュー式に細かいツールを並べるより、強力な1ツールのほうがエージェントが誤選択せず、毎セッションのコンテキストも節約できる」という計測結果に基づく。

ツール 用途
codegraph_explore ほぼ何でも1コールで回答。「Xはどう動く」「XからYへどう到達する」「この領域を俯瞰したい」——関連シンボルの本文をファイル別にまとめ、その間のコールパス(動的ディスパッチ含む)と影響半径を返す。クエリにファイル名やシンボル名を書けば、その現在のソースを行番号付きで読める(Readツールと同じ形)。

かつて公開されていたcodegraph_nodecodegraph_searchcodegraph_callerscodegraph_calleescodegraph_impactcodegraph_filescodegraph_status機能としては健在だがデフォルト非公開になった。これらが返す情報はexploreの応答(影響半径セクション、関係マップ、シンボル本体=呼び出し先一覧)にインラインで含まれるためだ。必要なら環境変数CODEGRAPH_MCP_TOOLS=explore,node,search,callersのように再公開できるし、CLIではcodegraph node/query/callers/callees/impact/files/statusとして常時使える。

.codegraph/がないルートでも、projectPathを渡せば別プロジェクト(モノレポ内の別サービスや第2のリポジトリ)を同一セッションで問い合わせられる。インデックスのないパスは「ビルトインツールを使え」というクリーンな案内を返すだけで、失敗しない。

エージェントは「直接答える」よう誘導される

MCPのinitialize応答でCodeGraphは使い方をエージェントに自動で伝える。要点は「構造的な質問はCodeGraphで直接答えよ——それが事前インデックスそのものなので、grep/readループは済んだ作業の繰り返しになる。返ったソースは既読として扱え。結果を信じ、grepで再検証するな。編集後はstalenessバナーを確認せよ」。

設計上の肝:探索をサブエージェントに丸投げさせない CodeGraphは直接クエリされたときだけ効く。だから指示は「探索をファイル読みのサブエージェントに委任せず、メインが直接答える」よう誘導する。委任してしまうと、サブエージェントがどのみちファイルを読み、CodeGraphは単なるオーバーヘッドになる。この点は[ハーネスエンジニアリング](/explain/harness-engineering/)の「メインはオーケストレーションに専念」という考え方と一見逆だが、CodeGraphに関しては「1コールで済むならメインで完結させる」のが正解になる。

CLIリファレンス:全コマンド一覧

MCPを使わずCLIから直接グラフを叩くこともできる。explore/nodeはMCPツールと同じ出力を返す。

codegraph                         # インタラクティブインストーラー
codegraph install                 # インストーラーを明示実行
codegraph uninstall               # 全エージェントからCodeGraph設定を除去(installの逆)
codegraph init [path]             # プロジェクト初期化+グラフ構築(1ステップ)
codegraph uninit [path]           # プロジェクトからCodeGraphを削除(--forceで確認スキップ)
codegraph index [path]            # フルインデックス(--forceで再インデックス、--quietで出力削減)
codegraph sync [path]             # 差分更新
codegraph status [path]           # 統計・保留同期の表示
codegraph unlock [path]           # インデックスを塞ぐ古いロックを除去
codegraph explore <query>         # 関連ソース+コールパスを一括取得(codegraph_exploreと同出力)
codegraph node <symbol|file>      # 1シンボルの本文+呼び出し元/ファイルを行番号付きで読む
codegraph query <search>          # シンボル検索(--kind / --limit / --json)
codegraph files [path]            # ファイル構造(--format / --filter / --json)
codegraph callers <symbol>        # 呼び出し元を列挙
codegraph callees <symbol>        # 呼び出し先を列挙
codegraph impact <symbol>         # 変更の影響範囲を分析(--depth)
codegraph affected [files...]     # 変更ファイルが影響するテストを特定
codegraph telemetry [on|off]      # 匿名利用統計の確認・切り替え
codegraph upgrade [version]       # 最新版へ更新(--check / --force)
codegraph help [command]          # ヘルプ

codegraph statusの出力イメージ(中規模TypeScriptプロジェクト):

CodeGraph Status
  Project: /Users/dev/my-app
  Index: initialized, 2,847 symbols, 8,124 edges
  Files: 312 indexed / 318 total
  Languages: TypeScript (198), JavaScript (47), CSS (67)
  Journal: wal
  Last sync: 2s ago

対応言語とフレームワーク:ゼロコンフィグで30言語超・17ルート検出

CodeGraphは設定なしでファイル拡張子から言語を自動判定する。1.0でObjective-C・R・Astroなどが加わり、さらにv1.3.0(2026-07-07)でNix・ArkTS(HarmonyOS)・Terraform/OpenTofu・CUDA・Solidity・Erlang・Visual Basic .NET・COBOL・CFMLが一挙に追加され、対応言語は30を超えた。インフラ定義(Terraform)やメインフレーム資産(COBOL)まで同じグラフに載る点が、汎用のコード検索ツールとの差になっている。

言語 拡張子 備考
TypeScript / JavaScript .ts/.tsx/.js/.jsx/.mjs フル対応
Python .py フル対応
Go / Rust .go / .rs フル対応
Java / C# .java / .cs フル対応
PHP / Ruby .php / .rb フル対応
C / C++ .c,.h / .cpp,.hpp,.cc フル対応
Objective-C .m,.mm,.h 部分対応(クラス・プロトコル・メソッド・@property・メッセージ送信)
Swift / Kotlin .swift / .kt,.kts フル対応
Scala .scala,.sc Scala 3 enum対応
Dart .dart フル対応
Svelte .svelte Svelte 5 runes・SvelteKitルート
Vue .vue script-setup・Nuxtルート
Astro .astro frontmatter+src/pages/ルート
R .R,.r S4/R5/R6クラス・source()参照
Liquid / Pascal・Delphi .liquid / .pasほか フル対応(DFM/FMXフォーム含む)
Lua / Luau .lua / .luau Luauは型エイリアス・Roblox require対応
Terraform / OpenTofu .tf,.tfvars,.tofu v1.3.0追加。モジュール境界を跨ぐ変数・出力の依存も辿れる
Nix .nix v1.3.0追加。flake・NixOS/home-managerモジュール・overlay
ArkTS .ets v1.3.0追加。HarmonyOS/OpenHarmonyの@Componentbuild()ツリー
CUDA .cu,.cuh v1.3.0追加。<<<grid, block>>>のホスト→カーネル呼び出しも接続
Solidity .sol v1.3.0追加。emitrevert・modifier・usingを辿る
Erlang .erl,.hrl v1.3.0追加。OTPのbehaviour/gen_serverディスパッチを追跡
Visual Basic .NET .vb v1.3.0追加。WinFormsデザイナ・Handles/WithEvents
COBOL .cbl,.cob,.cpy v1.3.0追加。PERFORM/CALL/COPY・CICSフロー
CFML .cfc,.cfm,.cfs v1.3.0追加。タグ形式とスクリプト形式の両方

フレームワークのルート検出は17種に拡張された。Webフレームワークのルーティング定義を認識し、routeノードとしてreferencesエッジでハンドラーに紐付ける。

フレームワーク 検出パターン(抜粋)
Django / Flask / FastAPI path()@app.route@app.get(...)ほか
Express / NestJS app.get(...)@Controller+@Get、GraphQL @Resolver
Laravel / Rails / Spring Route::get()get '/x', to:@GetMapping
Play / Drupal conf/routes*.routing.ymlhook_*
Gin・chi・mux / Axum・actix・Rocket r.GET(...).route("/x", get(h))
ASP.NET / Vapor [HttpGet("/x")]app.get("x", use:)
React Router / SvelteKit / Vue Router・Nuxt / Astro ファイルベースのルートノード

これにより「/api/usersエンドポイントを変更したとき、どのハンドラーが影響を受けるか」がcodegraph_explore一発で確認できる。

iOS / React Native / Expo の言語境界も橋渡し

1.0の目玉のひとつが混在iOS/RNコードベースの言語境界ブリッジだ。Swiftの呼び出しが@objcで自動ブリッジされたObjective-Cセレクタを叩く、JSがReact Nativeブリッジ経由でネイティブモジュールを呼ぶ、といった「静的解析が言語の壁で止まる箇所」をCodeGraphが繋ぐ。Swift↔ObjC、RNレガシーブリッジ(RCT_EXPORT_METHOD/@ReactMethod)、TurboModules、ネイティブ→JSイベント、Expo Modules、Fabric/Paperビューまでカバーし、codegraph_exploreのコールパスと影響半径が言語境界を越えて繋がる。各エッジにはprovenance:'heuristic'synthesizedBy(例:swift-objc-bridge)が付き、どう推定されたかが分かる。

codegraph affected:変更ファイルの影響テストを特定

codegraph affectedはインポート依存関係を推移的にトレースし、変更されたソースに影響されるテストファイルを特定する。CIで変更のないテストをスキップするのに使える。

codegraph affected src/utils.ts src/api.ts           # ファイルを引数で指定
git diff --name-only | codegraph affected --stdin    # git diffから直接パイプ
codegraph affected src/auth.ts --filter "e2e/*"      # テストファイルパターンを指定

CI/CDフック例——影響テストのみ実行:

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi
オプション 説明 デフォルト
--stdin ファイルリストをstdinから読み込む false
-d, --depth <n> 依存トレースの最大深度 5
-f, --filter <glob> テストファイルのglobパターン 自動検出
-j, --json JSON形式で出力 false
-q, --quiet ファイルパスのみ出力 false

大規模モノレポで全テストを毎回走らせている場合、このコマンドだけで大幅なCI時間削減が見込める。

ゼロコンフィグの哲学と除外ルール

CodeGraphは基本的に設定ファイルなしで動く。ここは旧バージョンから明確に変わったポイントだ。以前は「除外は.gitignoreのみ」だったが、1.0は依存・ビルド・キャッシュディレクトリを標準で自動除外する。

標準で除外されるもの(.gitignoreがなくても) node_modulesvendordistbuildtarget.venvPods.next などの依存・ビルド・キャッシュ系。加えて .gitignore記載パス(gitリポジトリではgit経由、非gitでは.gitignoreを直接読む)と 1MB超のファイル(生成バンドル・minified JS等)。
逆に除外されたディレクトリを取り込みたいときは .gitignore に否定 !vendor/ を書く。すでにコミット済みのディレクトリを外したいときは codegraph.jsonexclude(gitignore形式)に列挙する。

非標準拡張子(.tplをPHP扱い等)はcodegraph.jsonextensionsでマッピングできる。設定ファイルはこの1つだけで、しかも任意だ。

他のトークン削減ツールとの比較

CodeGraphはClaude Codeトークン最適化ツールのカテゴリでは「探索層の根本解決」という独自ポジションを占める。何を代替できるか——エージェントの探索フェーズそのものを置き換える。他ツールとのアプローチ比較を示す。

ツール アプローチ 削減対象 対応エージェント
CodeGraph ローカル知識グラフ(MCP) 探索ツールコール・ファイル読込 Claude Code・Cursor・Codex・Gemini・opencodeほか8種
RTK 出力フィルタリング(プロキシ) Claude Codeの出力冗長性 Claude Code専用
Token Savior MCPサーバー(シンボルナビ) ファイル読み込み操作 汎用MCPクライアント
claude-token-efficient CLAUDE.mdルール 出力フォーマット冗長性 Claude Code専用
Token Optimizer MCP 圧縮+SQLiteキャッシュ テキスト転送コスト 汎用MCPクライアント

CodeGraphの差別化点はエージェント非依存性の広さだ。Claude Code・Cursor・Codex・Gemini・Antigravity・Kiroほか8種に対応しており、チームで異なるエージェントを使っていても、プロジェクト内の.codegraph/という統一インデックスをどのエージェントからも共有できる。

一方で弱点もある。小規模リポジトリ(100〜200ファイル未満)ではトークン・コストの効果が薄く(速度は出る)、初期インデックス構築に数秒〜数分かかる。また「コードを書く」ツールコールは削減対象外で、あくまで「コードを探索する」フェーズのコストを下げる。

RTKとの組み合わせが有効 RTK(Rust Token Killer)はClaude Codeの出力フィルタリングに特化し、CodeGraphはコード探索を効率化する。アプローチが異なるため競合しない。大規模プロジェクトで両方を有効にすると、探索コストと出力冗長性の両方を削減できる。

トラブルシューティング

“CodeGraph not initialized”

対象プロジェクトでcodegraph initを実行していない。.codegraph/が存在しないとCodeGraphは有効化されない。

cd your-project
codegraph init

インデックスが遅い

node_modulesなどは標準で除外されるが、コミット済みの巨大ディレクトリはインデックス対象になる。codegraph.jsonexcludeで外し、--quietで出力オーバーヘッドを減らす。

MCPが”database is locked”を返す

現行ビルドはnode:sqliteのWALモードで動くため通常は起きない。起きる場合は、(1) pre-0.9の古いインストールを使っている(再インストールで解消)、(2) codegraph statusJournal:wal以外——ネットワーク共有やWSL2の/mntではWALを有効化できず読みが書きでブロックされることがある。プロジェクトをローカルディスク(WSLならLinuxネイティブの~/)に移す。

MCPがTransport closedで落ちる(statusは正常)

ほぼWSL2でプロジェクトがWindowsドライブ(/mnt/c等)にあるケース。CodeGraphはセッションをin-processにフォールバックするが、なお起きるならCODEGRAPH_NO_DAEMON=1をMCPサーバー環境に設定して共有サーバーを無効化する。

シンボルが見つからない

保存後2秒のデバウンス後に自動同期する(codegraph syncで手動同期も可)。ファイルの拡張子が対応言語か、.gitignoreや標準除外ディレクトリ内でないかを確認する。codegraph statusで統計と保留同期を確認できる。

まとめ

CodeGraphは「AIコーディングエージェントがコード探索に払うコスト」という見落とされがちな問題に正面から取り組んだOSSだ。1.0でMCPは単一ツールcodegraph_exploreに集約され、対応エージェントは8種に広がった。

7コードベース実測(Opus 4.8・中央値4回)を2026-08-05に測り直した最新値は、ツールコール88%削減・53%高速化・トークン62%削減・コスト44%削減・ファイル読み込みは7レポとも0件。旧値「58%削減・22%高速化」は対照群がCLIに到達できる汚染状態で測られており、公式自身がそれを開示して差し替えた。一方で、削減されるのは「処理した」トークンであって、セッション終了時に窓へ残る取得コンテキストは約80%増える(VS Codeで67k vs 18k)。自分に不利なこの数字まで公表している点も含めて、数値の受け取り方として重要だ。

curl一発・100%ローカル・Node.js不要のインストーラーという設計は導入障壁を下げている。中〜大規模プロジェクトで毎日Claude Codeを使っているなら、まずは速度のために試す価値が高い。

# 今すぐ試す(CLI導入 → 配線 → 初期化)
npx @colbymchenry/codegraph

参照ソース