CodeGraph完全解説｜Claude Codeのツールコールを58%減らすローカル知識グラフOSS（1.0）

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

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

2026年1月18日に公開されてから約半年、GitHubスター数は約56,900（2026-07-02時点）に達し、バージョンは1.0系（npm v1.2.0）へ到達した。実コードベース7種類のベンチマーク（Claude Opus 4.8・headless・中央値4回）では、CodeGraphなしと比べてツールコール平均58%削減・22%高速化・ファイル読み込みほぼゼロが確認されている。トークンやコストの削減幅は後述のとおり「規模依存」だが、探索の的確さと速度はどんなコードベースでも効く普遍的な効果だ。

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

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

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

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

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

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

主要スペック

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

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

ステップ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が対象の場合、自動許可パーミッションを設定

ステップ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段でグラフが構築・維持される。

ステップ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での変更も次の初回クエリで吸収する。

ベンチマーク：7コードベース実測（Opus 4.8で再検証）

READMEでは7つの実コードベースを使った詳細なベンチマークが公開されている。測定方法：Claude Opus 4.8をclaude -pのheadlessで実行し、同じアーキテクチャ質問をWITH（CodeGraphのMCP有効） vs WITHOUT（空のMCP設定） で各4回測定して中央値を比較。2026-06-02に現行ビルドで再検証されている。

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

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

このベンチマークで最も安定して現れるのはファイル読み込みの激減だ。表の「ファイル読込」列を見ると、CodeGraphありでは軒並み0、なしでは4〜9ファイル。CodeGraphありのエージェントはcodegraph_exploreが返した本文をそのまま読んで回答に入り、ほぼファイルを開かない。一方なしのエージェントは、正しいコードにたどり着く前にfind/ls/grepとReadで予算を使う。README自身が「普遍的な勝ち筋は的確なコンテキストと速度——ツールコール58%減・22%高速化・ファイル読込ほぼゼロ」と要約している。

トークン・コスト削減は「規模依存」

一方で、トークンとコストの削減幅は規模依存だと明記されている点は、旧バージョンから最も変わった見方だ。READMEはこう言う——コスト削減は「小規模で小さくノイジー、リポジトリ（とチーム）が大きく複雑になって初めて実費として効いてくる。500ファイル規模ではコストではなく速度のために採用せよ」。GoogleやMicrosoftのモノレポ級で、チーム全員の毎日のエージェント利用に掛け算されて初めて、コストは無視できない額に育つ。

なお個々の数値は実行ごとに揺れる（中央値4回でならしても裾は残る）。READMEは「Djangoのnoアームがあるバッチで$2.71/14分に振れた」例まで開示しており、Opus 4.8の再検証値は旧Opus 4.7時代より低いとも述べる。これはCodeGraphの退化ではなく、Opus 4.8がメインスレッドで効率よくgrep/Readするようになり、no-CodeGraph側のベースラインが強くなったためだ。ベンチマークをこの粒度で開示している姿勢は、数値の信頼性を測るうえで参考になる。

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

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

かつて公開されていたcodegraph_node・codegraph_search・codegraph_callers・codegraph_callees・codegraph_impact・codegraph_files・codegraph_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バナーを確認せよ」。

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

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

CodeGraphは設定なしでファイル拡張子から言語を自動判定する。1.0ではObjective-C・R・Astroなどが加わり、対応言語は20を超える。

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

これにより「/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

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

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

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

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

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

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

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

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

トラブルシューティング

“CodeGraph not initialized”

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

cd your-project
codegraph init

インデックスが遅い

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

MCPが”database is locked”を返す

現行ビルドはnode:sqliteのWALモードで動くため通常は起きない。起きる場合は、(1) pre-0.9の古いインストールを使っている（再インストールで解消）、(2) codegraph statusのJournal:が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・中央値）でのツールコール平均58%削減・22%高速化・ファイル読み込みほぼゼロは、どんな規模のコードベースでも効く普遍的な効果だ。一方でトークン・コストの削減幅は規模依存で、小規模では小さく、大規模モノレポ×チーム利用で初めて実費として効いてくる——READMEがこの区別を正直に開示している点は、数値の受け取り方として重要だ。

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

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

参照ソース

• colbymchenry/codegraph — GitHub
• @colbymchenry/codegraph — npm
• CodeGraph Documentation & Website