CodeGraph は、AI コーディングツール向けのローカルコード知識グラフです。プロジェクトを事前にインデックス化し、シンボル関係、コールグラフ、コード構造、ルート関係などを問い合わせ可能なグラフとして整理します。これにより Claude Code、Codex CLI、Cursor、OpenCode、Hermes Agent などは、毎回 grep、glob、Read、探索用サブエージェントに頼ってファイルを探す必要が減ります。
解決しているのは、とても実際的な問題です。AI Agent が大きなコードベースを見るとき、多くのコストはコード変更そのものではなく「コードがどこにあるか」を探すところで発生します。毎回検索し、読み、絞り込むと、token、時間、ツール呼び出しが消費されます。CodeGraph はまずコードベースをローカルの地図にし、Agent が具体的なファイルを読む前にその地図へ問い合わせられるようにします。
解決する主な痛点
小さなプロジェクトでは AI コーディングツールはたいてい問題なく動きます。ファイル数が少なく、検索も速く、読み取りコストも低いからです。しかしプロジェクトが大きくなると、よくある問題が出てきます。
- Agent がひとつのモジュールを理解するために、grep、find、ls、Read を何度も呼び出す。
- 探索用サブエージェントが無関係なファイルを大量に読むが、メインタスクの文脈はあまり明確にならない。
- アーキテクチャ質問で、ファイルの場所探しに多くの token を使う。
- 関数を変更する前に、誰が呼んでいて、その関数が何を呼ぶのか分かりにくい。
- Web プロジェクトで、URL ルートと実際のハンドラ関数の関係が直感的でない。
CodeGraph は、この「まず道を探す」作業を前倒ししようとします。インデックスができていれば、Agent は関連シンボル、呼び出し元、呼び出し先、影響範囲、コード片を直接問い合わせられます。
インストール方法
プロジェクトはクロスプラットフォームのインストールスクリプトを提供しており、ユーザーが自分で Node.js を準備する必要はありません。
|
|
Windows PowerShell では次を使えます。
|
|
すでに Node 環境がある場合は npm から直接使えます。
|
|
またはグローバルにインストールします。
|
|
インストーラは Claude Code、Cursor、Codex CLI、opencode、Hermes Agent など、インストール済みの Agent を検出して設定します。対応する MCP server 設定と指示ファイルを書き込み、これらのツールが CodeGraph をいつ呼ぶべきか分かるようにします。
プロジェクトの初期化
インストール後、対象プロジェクトでインデックスを作成します。
|
|
このコマンドはプロジェクト単位の知識グラフインデックスを作成します。README によると、プロジェクトに .codegraph/ ディレクトリが存在すれば、Agent は CodeGraph ツールを自動的に使えます。
使わなくなった場合は、グローバル設定を削除できます。
|
|
これはインストーラが書き込んだ MCP server 設定、指示、権限を削除します。プロジェクト内の .codegraph/ インデックスは自動削除されません。プロジェクトインデックスを削除するには codegraph uninit を使います。
Agent にとってなぜ役立つのか
Claude Code、Codex CLI、Cursor のようなツールは、コードベースを理解する前に探索を行いがちです。ファイルを探し、入口を読み、参照を調べ、呼び出しチェーンを追います。人間にとっては「プロジェクトを見て回る」作業ですが、モデルにとってはツール呼び出しとコンテキスト消費の連続です。
CodeGraph はこれをインデックス問い合わせに変えます。Agent はまず codegraph_context で関連する入口、シンボル、コード片を見つけ、その後 codegraph_explore などで必要な内容を読みます。利点は次のとおりです。
- 無関係なファイルを読む量が減る。
- 検索ツールの呼び出しが減る。
- 本当に関係するコードに早くたどり着ける。
- 変更前に影響範囲を見やすくなる。
- 大規模リポジトリのアーキテクチャ質問に答えやすくなる。
README のベンチマークでは、7 つの実際のオープンソースリポジトリで、CodeGraph ありとなしを比較しています。平均ではコスト、token、速度、ツール呼び出しの面で改善が見られます。具体的な数字はプロジェクト規模、言語、質問の種類、Agent の使い方によって変わりますが、大きなリポジトリほど事前インデックスの価値が出やすいことは明確です。
主な機能
1. スマートなコンテキスト構築
ひとつのツール呼び出しで、入口、関連シンボル、コード片を返せます。Agent が探索タスクを大量に投げてから絞り込む場面を減らせます。アーキテクチャ理解、モジュール特定、機能入口の分析に役立ちます。
2. 全文検索
CodeGraph は FTS5 を使って全文検索を行い、コードベース全体から名前やテキストを高速に探せます。すべての grep を置き換えるものではありませんが、Agent にとってより構造化された最初の探索地点になります。
3. 影響分析
関数、クラス、メソッド、ルートを変更する前に、callers、callees、影響範囲を問い合わせられます。リファクタリング、バグ修正、古いコード削除では、上流や下流の呼び出しを漏らすことが大きなリスクなので特に有用です。
4. 自動更新
README によると、CodeGraph は FSEvents、inotify、ReadDirectoryChangesW などのネイティブファイルシステムイベントと debounce auto-sync を使います。つまり、ローカルコードの変更に合わせてインデックスが自動更新され、ファイルを変更するたびに手動で再構築する必要はありません。
5. 多言語対応
プロジェクトは 19 以上の言語をサポートするとしています。TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Lua、Luau、Svelte、Liquid、Pascal / Delphi などが含まれます。
そのため、単一言語だけでなく、多言語リポジトリやフルスタックプロジェクトにも向いています。
6. Web ルート認識
CodeGraph は、多くの Web フレームワークのルートファイルやルート宣言も認識し、URL pattern とハンドラ関数を接続します。README では Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、Axum、ASP.NET、Vapor、React Router、SvelteKit などに触れています。
これは実用的です。多くの Web プロジェクトの本当の入口は、明確な main 関数ではなく、ルート、controller、handler、view、resolver です。Agent が URL と処理関数の関係を先に知っていれば、業務フローの理解がかなり速くなります。
ローカル優先の設計
CodeGraph は 100% local を強調しています。API key は不要で、外部サービスにも依存しません。インデックスデータはローカル SQLite データベースに保存されます。
企業プロジェクト、プライベートリポジトリ、機密コードでは、この設計が重要です。AI ツールをコードベースに接続するとき、心配されるのは「コードを見つけられるか」だけではなく、「コード構造やインデックスが外部へ送られないか」です。CodeGraph はローカル構築、ローカル問い合わせ、ローカルで Agent に提供する設計です。
もちろんローカルである以上、ディスク容量、インデックス時間、ファイル監視、プロジェクト規模も考える必要があります。非常に大きなリポジトリでは、初回初期化やその後の同期にもリソースが必要です。
向いている場面
CodeGraph は次のような場面に向いています。
- 大規模コードベースで、アーキテクチャや呼び出しチェーンの質問が多い。
- Claude Code、Codex CLI、Cursor などの Agent でコード理解や変更を行う。
- Agent があちこちのファイルを読み、広く検索し、探索を繰り返す状況を減らしたい。
- 変更前に影響範囲を分析したい。
- Web プロジェクトのルートが複雑で、URL からハンドラを素早く見つけたい。
- チームとして AI Agent に安定したローカルプロジェクトインデックスを与えたい。
数十ファイル程度の小さなプロジェクトなら、普通の検索で十分かもしれません。CodeGraph が最も価値を出すのは、中規模から大規模のコードベースで、Agent に探索をよくさせる場面です。
使うときの注意点
第一に、CodeGraph はコードレビューやテストの代替ではありません。Agent が関連コードを早く見つける助けにはなりますが、変更が必ず正しいことは保証しません。
第二に、インデックス品質が結果に影響します。複雑な構造、大量の生成コード、混在言語、除外されていない build 生成物があると、インデックスがノイズを含みやすくなります。使う前に .gitignore、プロジェクト構成、インデックス範囲を確認したほうがよいでしょう。
第三に、MCP 設定と Agent 指示が重要です。README でも、CodeGraph は正しく問い合わせられたときに効果があると説明しています。Agent がそれを無視して大量のファイルを直接読むなら、事前インデックスは追加コストになります。
第四に、ローカルツールであっても権限には注意が必要です。インストーラは Agent 設定と権限リストを書き込みます。チーム環境では、これらの設定をまとめて確認するほうが安全です。
まとめ
CodeGraph の価値は、AI Agent にローカルのコード地図を渡すことだと理解できます。モデルを賢くするのではなく、モデルが迷いにくくなるようにします。
Claude Code、Codex CLI、Cursor などが大規模リポジトリに向き合うとき、コンテキストを多く消費するのは探索です。CodeGraph は事前インデックス化されたシンボル関係、コールグラフ、ルートグラフ、全文検索によって「コードを探す」段階を先に済ませ、Agent が理解と変更により多くの予算を使えるようにします。
実際のプロジェクトで AI コーディングツールを使っていて、「たくさんファイルを読んだのに要点を見つけられない」場面が多いなら、CodeGraph は試す価値があります。これは AI コーディングツールの重要な方向性を示しています。より強いモデルだけでなく、そのモデルにより良いローカルコードコンテキストを与えることも必要です。
参考資料：
- GitHub プロジェクト：https://github.com/colbymchenry/codegraph