はじめに
Claude Code等のAIエージェントを使用する中で、こんな経験はないでしょうか。
「このエンドポイント、どこで処理されてるんだっけ？」
→ Claude に聞く → 「ファイルにGrepをかけて探しに行く」
→ 「このファイルだけでは判断できません」
→ また別のファイルを探す……
コードが増えてくると、Claude Code 単体では答えに辿り着くまでにファイルの grep と読み込みを何度も繰り返すため、トークンコストがかさみ、回答も遅くなります。
そこで最近話題のCodeGraphを試してみました。
CodeGraph とは
CodeGraph はコードベース全体を SQLite のナレッジグラフとしてインデックス化する MCP サーバーです。
関数・クラス・変数などのシンボルと、それらの呼び出し関係・依存関係をグラフ構造で DB に保持します。
AIエージェントはコードを探す際にファイルを grep するのではなく、DB に問い合わせるため、大量のファイルを読み込まずに必要な情報を取得できます。
※「CodeGraph」という名前は他のリポジトリでも使用されています。
本記事で紹介するのは colbymchenry/codegraph です。
主な特徴は以下のとおりです。
| 特徴 | 説明 |
|---|---|
| Smart Context Building | 1回のツール呼び出しでエントリポイント・関連シンボル・コードスニペットをまとめて取得できます。探索エージェントを何度も走らせるコストが不要になります |
| Full-Text Search | SQLite 組み込みの全文検索エンジン（FTS5）を活用し、コードベース全体からシンボルを名前で即座に検索できます |
| Impact Analysis | 任意のシンボルの呼び出し元・呼び出し先と影響範囲を、変更前に一覧できます |
| Always Fresh | OS ネイティブのファイル監視イベント（FSEvents / inotify / ReadDirectoryChangesW）とデバウンスによる自動同期で、コーディング中もグラフが常に最新の状態を保ちます。設定不要です |
| 20+ 言語対応 | TypeScript・JavaScript・Python・Go・Rust・Java・C#・PHP・Ruby・C・C++・Objective-C・Swift・Kotlin・Dart・Lua・Svelte など 20 言語以上に対応しています |
| フレームワーク対応ルート解析 | 14 のWebフレームワークの routing ファイルを認識し、URL パターンとハンドラを紐付けます |
| iOS / React Native / Expo 対応 | Swift ↔ ObjC ブリッジ、React Native の TurboModules / Fabric、ネイティブ → JS イベントエミッターなど、静的解析では追いにくいクロスランゲージのフローを把握できます |
| 100% ローカル | データは外部に送信されません。SQLite のみで完結します |
セットアップ
インストール
npxコマンドでインストールが可能です。
初期セットアップやMCPのセットアップまでやってくれました。
初回は数分かかります（1,700 ファイルで 2〜3 分程度）。
以降はファイルウォッチャーが差分を自動更新してくれます。
npx @colbymchenry/codegraph
使い方
ユーザーは自然言語で指示するだけです。MCP サーバーとして登録されているため、Claude が状況に応じて自動で CodeGraph のツールを選択・呼び出してくれます。導入前後で、Claude が裏側で呼び出すツールがどう変わるかを見てみましょう。
Before：AIエージェントはファイルを探す→読むを繰り返す
ユーザー：「/api/sample エンドポイントの処理の流れを教えて」 Claude の裏側： 1. Bash(grep "sample" routes/) → ファイルを特定 2. Read(routes/sample.py) → ルート定義を読む 3. Bash(grep "SampleService" ./) → サービス層を特定 4. Read(services/sample_service.py) → サービスを読む 5. Bash(grep "SampleRepository" ./) → リポジトリ層を特定 6. Read(repositories/sample_repo.py) → リポジトリを読む …（ツール呼び出し多数）
必要なファイルを一つひとつ grep → Read する往復が続き、コンテキストをどんどん消費します。
After：DB への問い合わせ
ユーザー：「/api/sample エンドポイントの処理の流れを教えて」
Claude の裏側：
1. codegraph_trace(from="partners route", to="DB")
→ router → service → repository → model の呼び出し経路を即座に返す
自然言語の質問をそのまま渡すだけで、Claude が適切な CodeGraph ツールを選んで DB に問い合わせます。
ファイルを読みに行く往復がなくなり、ツール呼び出しが大幅に減ります。
数字で見るコスト削減効果
公式ベンチマークでも効果が数値で確認されています。
7つの実際のOSSを対象に、CodeGraph あり／なしで Claude Codeがアーキテクチャに関する質問に答えるタスクを比較した結果です。
平均：コスト 25% 削減・トークン数 57% 削減・処理時間 23% 短縮・ツール呼び出し数 62% 削減
| コードベース | 言語 | コスト | トークン数 | 処理時間 | ツール呼び出し数 |
|---|---|---|---|---|---|
| VS Code | TypeScript（約 10,000 ファイル） | 33% 削減 | 70% 削減 | 27% 短縮 | 80% 削減 |
| Excalidraw | TypeScript（約 640 ファイル） | 27% 削減 | 61% 削減 | 26% 短縮 | 70% 削減 |
| Django | Python（約 3,000 ファイル） | 23% 削減 | 70% 削減 | 28% 短縮 | 77% 削減 |
| Tokio | Rust（約 790 ファイル） | 35% 削減 | 70% 削減 | 37% 短縮 | 79% 削減 |
| OkHttp | Java（約 645 ファイル） | 11% 削減 | 48% 削減 | 26% 短縮 | 70% 削減 |
| Gin | Go（約 110 ファイル） | 15% 削減 | 35% 削減 | 9% 短縮 | 47% 削減 |
| Alamofire | Swift（約 110 ファイル） | 28% 削減 | 46% 削減 | 7% 短縮 | 13% 削減 |
特に効いたケース
影響範囲調査：「この共通関数を修正したい。どこに影響する？」と聞くと、codegraph_impact で呼び出し元を全列挙してくれます。
新規参画時の理解：新しい機能を触るとき、まず codegraph_context に「この機能の概要を把握したい」と伝えると、関連シンボルをまとめて返してくれます。ドキュメントがなくてもコード全体を把握することが可能です。
おわりに
生成 AI を活用する際、フロントエンド・バックエンド・インフラをまとめて管理できるモノレポ構成を採用しているチームも多いのではないでしょうか。
モノレポは AI がコードベース全体を見渡しやすいという利点がある一方で、ファイル数が増えるほどコンテキストが逼迫しやすいという課題もあります。
Codegraph はまさにその課題を解決してくれます。grep とファイル読み込みの往復が DB への問い合わせ 1 回に変わるだけで、レスポンスの速さも精度も体感できるほど変わりました。
モノレポや大規模コードベースで AI エージェントを使っている方には、ぜひ一度試してみてください。
簡単30秒