CodeGraph完全解説｜Claude Codeのツールコール70%削減・コスト35%節約するローカル知識グラフOSS

Claude Codeで大規模なコードベースを扱うとき、見えないコストが積み上がっていく。「このモジュールはどこで定義されている？」——そのたびにエージェントはgrep・glob・Readを連打し、ファイルを読み漁り、サブエージェントを生成し、トークンを消費し続ける。1回の質問で20〜80回のツールコールが発生することも珍しくない。

CodeGraphはこの問題の根本を狙う。ソースコードをtree-sitterでAST解析し、すべてのシンボル・関数呼び出し・クラス継承・インポート関係をローカルのSQLiteデータベースに格納する。Claude Code（とCursor・Codex CLI・opencode・Hermes Agent）はそのグラフをMCPサーバー経由でクエリするだけでよく、ファイルを直接読む必要がなくなる。

2026年1月18日に公開されてから約4ヶ月、GitHubスター数は13,295（2026-05-21時点）に達した。実コードベース7種類のベンチマーク（中央値4回測定）では、なにもしない状態と比べて平均35%のコスト削減・70%のツールコール削減が確認されている。

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

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

CodeGraphの設計思想は「エージェントに渡す地図を事前に作る」ことだ。

AIコーディングエージェントがコードを探索する従来の方法はこうだ。まずgrep/globでファイルを見つけ、Readツールでファイルを開き、内容を確認し、別のファイルにジャンプし、また読む……この探索ループがトークンとツールコールを消費する。大きなリポジトリほどこのコストは爆発的に増える。Claude Code v2.1の内部実装では、この探索作業をExploreエージェントがサブタスクとして受け持つが、そのExploreエージェント自体が大量のReadを連打する構造になっている。

CodeGraphはこのループを断ち切る。インデックス構築時に一度だけソースコードをパースし、シンボル（関数・クラス・メソッド・変数）とエッジ（呼び出し・継承・インポート）をSQLiteに保存する。エージェントが「UserServiceの定義を見せて」と要求すると、CodeGraphは1回のクエリでシンボルの定義・コードスニペット・呼び出し元・呼び出し先を返す。ファイルを開く必要がない。

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

主要スペック

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

インタラクティブインストーラー（推奨）

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

# 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がある場合
npx @colbymchenry/codegraph

# グローバルインストール
npm i -g @colbymchenry/codegraph

npx @colbymchenry/codegraphを実行するとインタラクティブインストーラーが起動する。インストーラーは以下を自動で行う。

1. インストール済みのエージェントを自動検出（Claude Code・Cursor・Codex CLI・opencode・Hermes Agent）
2. 対象エージェントを選択（複数可）
3. codegraphをPATHにインストール（MCPサーバー起動用）
4. 設定をグローバル（全プロジェクト共通）またはローカル（プロジェクト固有）に書き込む
5. 各エージェントのMCP設定ファイルと指示ファイル（CLAUDE.md等）を自動更新
6. Claude Codeが対象の場合、settings.jsonに自動許可パーミッションを追記

インストール後にエージェントを再起動し、プロジェクトで初期化する。

cd your-project
codegraph init -i     # -i フラグでインデックスも同時構築

.codegraph/ディレクトリが作成され、codegraph.dbにインデックスが格納される。この.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を編集する。

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

加えて~/.claude/settings.jsonに自動許可設定を追加すると、毎回の確認ダイアログが不要になる。

{
  "permissions": {
    "allow": [
      "mcp__codegraph__codegraph_search",
      "mcp__codegraph__codegraph_context",
      "mcp__codegraph__codegraph_callers",
      "mcp__codegraph__codegraph_callees",
      "mcp__codegraph__codegraph_impact",
      "mcp__codegraph__codegraph_node",
      "mcp__codegraph__codegraph_status",
      "mcp__codegraph__codegraph_files"
    ]
  }
}

MCP設定の詳細は MCPサーバー構築ガイド も参照されたい。

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

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

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

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

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

ステップ3：参照解決

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

ステップ4：自動同期

MCPサーバーがネイティブOSのファイルイベントを監視する。ファイル変更を検知して2秒のデバウンス後、変更されたソースファイルのみを差分インデックスする。ソースファイル以外（バイナリ・ログ等）は自動でフィルタされ、.gitignoreで除外されたパスも対象外になる。エディタで保存するたびにグラフが自動更新されるため、手動同期は不要だ。

ベンチマーク：7コードベース実測の詳細

CodeGraphのREADMEでは7つの実コードベースを使った詳細なベンチマークが公開されている。測定方法：Claude Opus 4.7・Claude Code v2.1.145をheadlessモードで実行し、同じアーキテクチャ質問をWITH（CodeGraph有効） vs WITHOUT（MCPなし） で各4回測定して中央値を比較した。

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

規模と効果の関係

ベンチマークで明確に見えるのはリポジトリ規模と効果の相関だ。Ginのような小規模リポジトリ（約150ファイル）ではツールコール削減が19%に留まる。これはgrep/findを使ったネイティブ探索がもともと安価なためだ。一方でVS Code（約10Kファイル）やTokio（Rust、約700ファイル・89%削減）では効果が大きく出る。

特にRustやTypeScriptのような型システムが複雑な言語では、シンボル間の参照が多く、型情報・トレイト実装・ジェネリクスの追跡が探索コストを増大させる。CodeGraphがそれを事前解決していることが高い削減率につながっている。

なぜCodeGraphが有利なのか

READMEが説明するメカニズムはシンプルだ。「CodeGraphがある場合、エージェントはcodegraph_contextでエリアをマッピングし、codegraph_exploreで必要なソースを取得して終わる。ファイル読み込みがゼロになる。」逆にCodeGraphがなければ、エージェント（とその子エージェント）はdiscovery（find/ls/grep）に予算の大半を使い、正しいコードを読む前に疲弊する。

MCPツール：8つのインターフェース

CodeGraphがMCPサーバーとして公開する8つのツールがエージェントのインターフェースとなる。

メインセッションとExploreエージェントの使い分け

READMEの指示では、メインセッションでcodegraph_exploreとcodegraph_contextを直接呼ばないことと明記されている。これらは大量のソースコードを返すためメインセッションのコンテキストを圧迫する。メインセッションからはcodegraph_search・codegraph_impact・codegraph_nodeなどの軽量ツールのみを使い、探索はExploreエージェントに委任するのが推奨設計だ。

この分担はClaude Codeのハーネスエンジニアリングの考え方と一致する。メインセッションはオーケストレーションに専念し、コンテキストを汚すような大量データ取得はサブエージェントに任せる。

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

# インストーラー実行
codegraph                         # インタラクティブインストーラー
codegraph install                 # インストーラーを明示的に実行

# プロジェクト管理
codegraph init [path]             # プロジェクト初期化（--index でインデックスも構築）
codegraph uninit [path]           # CodeGraphをプロジェクトから削除（--force で確認スキップ）

# インデックス操作
codegraph index [path]            # フルインデックス（--force で再インデックス）
codegraph sync [path]             # 差分更新
codegraph status [path]           # 統計表示

# クエリ
codegraph query <search>          # シンボル検索（--kind / --limit / --json）
codegraph files [path]            # ファイル構造表示（--format / --filter / --json）
codegraph context <task>          # AIコンテキスト構築（--max-nodes / --format）

# CI統合
codegraph affected [files...]     # 変更ファイルが影響するテストを特定
codegraph serve --mcp             # MCPサーバー起動

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言語をゼロコンフィグで

CodeGraphは設定なしでファイル拡張子から言語を自動判定する。対応言語は以下の通りだ。

1MBを超えるファイルは自動的にスキップされる（生成済みバンドル・minified JSなど）。.gitignoreで除外されたパスも対象外だ。

フレームワーク対応：ルート検出機能

CodeGraphのユニークな機能のひとつがフレームワーク対応のルート検出だ。Webフレームワークのルーティング定義ファイルを認識し、routeノードとしてreferencesエッジでハンドラー関数・クラスに紐付ける。

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

ライブラリAPIとしての使用

CLIやMCPサーバーとしてだけでなく、TypeScriptライブラリとして組み込むこともできる。

import CodeGraph from '@colbymchenry/codegraph';

// 初期化（既存インデックスがなければ自動作成）
const cg = await CodeGraph.init('/path/to/project');
// または既存インデックスを開く
// const cg = await CodeGraph.open('/path/to/project');

// フルインデックス構築（プログレス付き）
await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});

// シンボル検索
const results = cg.searchNodes('UserService');
console.log(results[0].node); // { id, name, kind, file, line, ... }

// 呼び出し元を取得
const callers = cg.getCallers(results[0].node.id);

// タスク用コンテキスト構築（Markdown形式）
const context = await cg.buildContext('fix login bug', {
  maxNodes: 20,
  includeCode: true,
  format: 'markdown'
});

// 変更影響範囲を分析
const impact = cg.getImpactRadius(results[0].node.id, 2);

// ファイル変更の自動監視
cg.watch();   // 有効化
cg.unwatch(); // 停止
cg.close();   // リソース解放

CI環境でCodeGraphをライブラリとして使い、デプロイ前にシンボルの影響範囲チェックを自動化する用途が想定されている。

codegraph affected：変更されたファイルの影響テストを特定

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

# ファイルを引数で指定
codegraph affected src/utils.ts src/api.ts

# git diffから直接パイプ
git diff --name-only | codegraph affected --stdin

# テストファイルパターンを指定
codegraph affected src/auth.ts --filter "e2e/*"

# CI/CDフック例：影響テストのみ実行
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

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

ゼロコンフィグの哲学

CodeGraphには設定ファイルがない。これは意図的な設計判断だ。

この設計の利点は「追加の設定ファイルがコードレビューに混入しない」「チームメンバー間で設定が食い違わない」「CIで動作検証しやすい」ことだ。欠点は.gitignoreを適切に管理していないリポジトリでは余分なファイルがインデックスされる可能性があることだが、tree-sitterが解析できないバイナリファイルや1MB超のファイルは自動スキップされるため実害は限定的だ。

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

CodeGraphはClaude Codeトークン最適化ツールのカテゴリでは「探索層の根本解決」という独自ポジションを占める。他ツールとのアプローチ比較を示す。

CodeGraphの差別化点はエージェント非依存性だ。Claude Code・Cursor・Codex CLIすべてに対応しており、チームで異なるエージェントを使っていても統一したインデックスを共有できる（プロジェクト内の.codegraph/はどのエージェントからも参照される）。

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

トラブルシューティング

“CodeGraph not initialized”

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

cd your-project
codegraph init -i    # 初期化＋インデックス構築

インデックスが遅い

node_modulesや大きなビルド成果物が.gitignoreに含まれているか確認する。除外されていない場合はインデックス対象になる。--quietフラグで出力オーバーヘッドを削減できる。

MCPが”database is locked”を返す

v0.9以前のビルドを使っている場合に発生する。現行バージョンはバンドル済みNode.jsランタイムを使いWALモードで動作するため、通常の並行読み取りではロックしない。

# 最新版に更新
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# または
npm i -g @colbymchenry/codegraph@latest

WSL2の/mnt経由でアクセスしているファイルシステムや、ネットワークマウントされたドライブでは、WALモードが有効化できずロックが発生することがある。この場合はプロジェクトをローカルディスクに移動する。

シンボルが見つからない

• MCPサーバーがファイル保存後2秒のデバウンド後に自動同期する。codegraph syncで手動同期も可能
• ファイルの拡張子が対応言語に含まれているか確認する
• codegraph statusでインデックスの統計を確認する

MCPサーバーが接続できない

• codegraph serve --mcpがコマンドラインから動作するか確認する
• MCP設定ファイルのcommandパスが正しいか確認する（which codegraphで確認）
• プロジェクトがcodegraph init済みか確認する

まとめ

CodeGraphは「AIコーディングエージェントがコード探索に払うコスト」という見落とされがちな問題に正面から取り組んだOSSだ。

7コードベース実測の中央値ベースでツールコール平均70%削減・コスト35%削減という数字は実用的な水準にある。特にRustやTypeScriptの大規模リポジトリ（Tokio：89%削減、VS Code：72%削減）では効果が顕著だ。

ゼロコンフィグ・100%ローカル・Node.js不要のインストーラーという設計は導入障壁を下げている。Claude Code・Cursor・Codex CLIという主要エージェントをすべてカバーしていることも実践的な強みだ。

弱点は小規模リポジトリでの限界効用低下と、「コードを書く」フェーズへの無効性だが、中〜大規模プロジェクトで毎日Claude Codeを使っているなら試す価値は高い。

# 今すぐ試す
npx @colbymchenry/codegraph

インストーラーが30秒で設定を済ませてくれる。

参照ソース

• colbymchenry/codegraph — GitHub
• @colbymchenry/codegraph — npm