CodeGraph——AIコーディングエージェントに「コードの地図」を渡すMCPツール
Claude CodeやCursorに事前インデックス済みのコード知識グラフを提供し、トークン数を59%削減、ツール呼び出しを70%削減するCodeGraphのセットアップと使い方を解説。
Claude CodeやCursorに事前インデックス済みのコード知識グラフを提供し、トークン数を59%削減、ツール呼び出しを70%削減するCodeGraphのセットアップと使い方を解説。
📑 目次
みなさん、こんにちは！葉桜ラボ編集部のチカちゃんです 🌸
ここ数ヶ月、AIコーディングエージェント（Claude Code、Cursor、Codex CLI、OpenCode……）がめっちゃ流行ってますよね。「もうターミナルで直接コード書くのが面倒になった……」なんて人も増えてきたんじゃないでしょうか。
でも、使ってるとこんなモヤモヤ、ありませんか？
- 「この関数、どこで定義されてるんだっけ？」→ エージェントがgrep＆ファイル読み込みを延々と繰り返す
- 大規模リポジトリになると、コンテキストがすぐパンク
- 結局「探索」にトークンと時間を大量消費して、肝心のコードを書く前に課金が……💸
今日紹介する CodeGraph は、この「エージェントの手探り問題」を解決するために生まれたツールです。
そもそもCodeGraphって何？
CodeGraph は、AIコーディングエージェント（Claude Code / Cursor / Codex CLI / OpenCode）に対して、事前インデックス済みのコード知識グラフを提供するMCPサーバーです。
https://github.com/colbymchenry/codegraph
通常、エージェントはコードベースを理解しようとするとき、「grepで検索 → ファイルを読む → また検索」という試行錯誤を繰り返します。これは人間が初めてのコードベースを探索するのと同じで、すごく非効率。
CodeGraphはその前に、tree-sitterでコードの構造を解析し、関数・クラス・インポート・呼び出し関係をSQLiteのグラフとしてあらかじめインデックスしておきます。エージェントはそのグラフをクエリするだけで、一発で必要な情報を手に入れられる——という仕組みです。
特筆すべきは、すべてローカルで完結していること。データはあなたのマシン内のSQLiteデータベースに保存され、外部に漏れることはありません。APIキーも不要です。
どれくらいすごいの？（ベンチマーク）
CodeGraphのREADMEには、実際のリポジトリを使った比較データが載っています。めちゃくちゃ具体的なので一部抜粋：
| 指標 | CodeGraphあり | CodeGraphなし | 改善 |
|---|---|---|---|
| ツール呼び出し回数（平均） | 3回 | 39回 | 92%削減 |
| 処理時間（平均） | 27秒 | 1分33秒 | 71%高速化 |
| ファイル読み込み | 0回 | 多数 | 100％削減 |
| 使用トークン（平均） | 59.4K | 236.7K | 75%削減 |
特に面白いのはVS Code本体（4,002ファイル、59,377ノード）でのテスト。CodeGraphを使ったエージェントは たった3回のツール呼び出し＋17秒 で複雑な質問に答えています。使わなかった場合は 52回の呼び出し＋1分37秒。この差はデカい……。
また、Swiftコンパイラ（25,874ファイル、272,898ノード）という超大規模リポジトリでも、CodeGraphは4分でインデックス完了し、エージェントは 6回の探索呼び出し＋ファイル読み込み0回＋35秒 で質問に回答できたそうです。
※ ベンチマークはClaude Opus 4.7 + Claude Code v2.1.145、各4回実行の中央値。詳細は公式READMEをどうぞ。
インストール＆セットアップ手順
基本、ターミナルで 3つのコマンド を叩くだけです。
Step 1: インタラクティブインストーラーを実行
npx @colbymchenry/codegraphこれを実行すると、対話形式のインストーラーが起動します。自動で以下のことをやってくれます：
- インストール済みのエージェントを検出（Claude Code / Cursor / Codex CLI / OpenCode）
- MCPサーバーの設定を自動で書き込み（
~/.claude.jsonなど） - 各エージェント用の指示ファイルを作成（
CLAUDE.md、.cursor/rules/codegraph.mdcなど） - 「グローバルインストール」か「このプロジェクトだけ」かを質問してくる
途中で「codegraphをPATHに追加しますか？」と聞かれるので、基本的には Yes で大丈夫です。
Step 2: プロジェクトを初期化
cd your-project
codegraph init -iこのコマンドで、そのプロジェクトのコード解析が始まります。プロジェクト内に .codegraph/ ディレクトリが作成され、その中に知識グラフのデータベースが保存されます。
Step 3: エージェントを再起動
設定が完了したら、使っているエージェント（Claude CodeやCursorなど）を再起動します。すると、エージェントがCodeGraphのMCPツールを自動認識し、コード探索に使い始めます。
非インタラクティブモード（CI / スクリプト向け）
サーバーやCIで使うなら、フラグで全部指定できます：
# 自動検出 + 全自動グローバルインストール
codegraph install --yes
# 特定のエージェントだけ指定
codegraph install --target=cursor,claude --yes
# プロジェクトローカルにインストール
codegraph install --target=auto --location=local実際の使い方——エージェントとの連携
セットアップが完了すると、エージェントが以下のようなツールを使えるようになります。
メインセッションで使う軽量ツール
| ツール | 用途 |
|---|---|
codegraph_search | シンボル名でコード全体を検索（FTS5） |
codegraph_callers | ある関数を呼び出している箇所を検索 |
codegraph_callees | ある関数が呼び出している先を検索 |
codegraph_impact | シンボル変更の影響範囲を分析 |
codegraph_node | 個別シンボルの詳細情報を取得 |
codegraph_files | インデックスされたファイル構造を表示 |
codegraph_status | インデックスの状態を確認 |
サブエージェントで使う探索ツール
深い調査が必要な場合は、サブエージェント（Explore agent） を起動して codegraph_explore を使います。このツールは、関連する全ファイルのソースコードを一度に返してくれるので、エージェントが何度もファイルを読みに行く必要がなくなります。
実際のやりとりイメージ
たとえば、Claude Codeに 「このプロジェクトの認証フロー、どうなってる？」 と聞いたとします。
CodeGraphなしの場合：
- “auth” でgrep → たくさん出てくる
- 関連ファイルを順番に読む（何度もRead tool呼び出し）
- 呼び出し関係を推測しながら探索
- 合計50回くらいツール呼び出し、トークンは数十万
CodeGraphありの場合：
codegraph_search("auth")→ 関連シンボルが一発で見つかるcodegraph_callers / callees→ 呼び出し関係がパッとわかる- サブエージェントで
codegraph_explore→ 該当コードをまとめて取得 - 合計3〜5回のツール呼び出し、ファイル読み込みゼロ
この差は、実際に使うと本当に体感できます。特に大きめのリポジトリ（数千ファイル以上）だと顕著です。
ここがすごい——競合との差別化ポイント
CodeGraphのすごいところ、いくつかまとめてみます。
1. 「エージェントに読み方を教える」設計が秀逸
インストーラーが作成する指示ファイル（CLAUDE.mdなど）には、「codegraph_exploreをメインのツールとして使い、取得したコードは再読み込みしない」 というルールが明示されています。つまり、エージェントの行動を根本から変える設計。単なる検索ツールを追加するのではなく、エージェントの「探索戦略」そのものを最適化しています。
2. 100%ローカル
データが一切外部に出ません。SQLiteベースなので、オフラインでも使えるし、企業のセキュリティポリシーにも引っかかりにくい。「AIエージェントにコード全部読ませるの怖い……」 という懸念も、CodeGraphなら安心です。
3. フレームワークを理解する
13種類のWebフレームワーク（Django, Flask, FastAPI, Express, NestJS, Laravel, Rails, Spring, Gin, Axum, ASP.NET, Vapor, React Router）のルーティングパターンを自動認識します。つまり、「このURLのハンドラはどこ？」 という質問にも、フレームワークのルールに従って正確に答えてくれます。
4. 自動同期
ファイル変更をOSネイティブのファイルイベント（FSEvents / inotify / ReadDirectoryChangesW）で検出し、2秒のデバウンスで自動インデックス更新してくれます。コードを書きながら知識グラフが自動で最新に保たれる、というわけです。
5. 多言語対応
19言語＋αに対応。TypeScript/JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Swift、Kotlin、Scala、Dart、Svelte、Vue、Liquid、Pascal……。言語をまたがったクエリ（Pythonの関数からRustの実装を追う、等）もシームレスに動くのが面白いところ。
気をつけること
インデックス初回作成の時間
大規模リポジトリ（Swiftコンパイラクラス）でも4分程度ですが、プロジェクトによってはそれなりに時間がかかります。初回は気長に待ちましょう。2回目からは差分だけの同期なので一瞬です。
対応エージェントのバージョン
Claude Code / Cursor / Codex CLI / OpenCode の4つに対応。WindsurfやContinueなどはまだ公式対応されていません（ただしREADME曰く、targets/ に1ファイル追加＋registry登録で簡単に追加できる設計になっているとのこと）。
「エージェントに任せすぎ」にならないように
便利だからといって、すべてをエージェント任せにするのは考えもの。CodeGraphは「コードを理解する」ためのツールであって、「コードを考える」ためのツールではありません。ツールを使って判断するのは自分——という意識は忘れずに持ちたいところです。
まだ発展途上
GitHubのスター数は12,000超えで急成長中ですが、まだv0.8.0（2026-05-20リリース）。機能は安定していますが、破壊的変更が入る可能性はゼロではありません。アップデートはREADMEやリリースノートをチェックしておきましょう。
チカちゃん的まとめ
CodeGraphは、「AIコーディングエージェントがコードを読むコスト」を根本から下げる ツールです。
ここでちょっと哲学的になるんですけど——エージェントが「手探りでコードを読む」のと「知識グラフを引く」のとでは、情報の扱い方が根本的に違います。手探りは推測を含むけど、グラフは構造をそのまま返す。つまりCodeGraphは、エージェントの「勘」を減らして「確度」を上げる——「考える」ために使うトークンを増やす、とも言えます。
コードを書く人間にとっても、自分でgrepしなくてもエージェントが一発で該当箇所を教えてくれるのは、「考える文脈を途切れさせない」 という意味で大きな価値があります。
気になった方は、まずお試しで小さなプロジェクトに npx @colbymchenry/codegraph してみてください。3コマンドで終わります。もし「こんなに変わるんだ……」と感じたら、チカちゃん的に大成功です。
思索は冒険です。今日の話も、その入口のひとつでした 🌸
参考URL
- CodeGraph リポジトリ → https://github.com/colbymchenry/codegraph
- npm パッケージ → https://www.npmjs.com/package/@colbymchenry/codegraph
- 公式README（最新のベンチマークあり） → https://github.com/colbymchenry/codegraph/blob/main/README.md
- インターネット上のツールは第三者が提供するものです。開発工程や配布経路を悪用した攻撃（サプライチェーン攻撃）が仕掛けられる可能性もゼロではありません。ご利用の際は公式リポジトリの情報をご確認いただき、自己責任でお使いください。
- AIに関する技術や情報は急速に変化します。本記事の内容が公開後に古くなる可能性があります。各サービスの公式ドキュメントや最新情報をご確認ください。