💻 AIコーディングのToken消費を57%削減！コード知識グラフ「CodeGraph」が32K Star突破

はじめに

Claude CodeやCursor、CodexといったAIコーディングツールを日常的に使っていると、誰もが同じ壁にぶつかる。

「この機能はどこで実装されている？」「認証フローを整理して」「このモジュールを変更すると何が影響を受ける？」——こうした質問を投げるたびに、AIはプロジェクト全体を探索し始める。数十のファイルを読み込み、数百回の検索を実行し、数百万Tokenを消費する。APIの請求書を開くたびに胃が痛くなる。

さらに厄介なのは、これだけTokenを消費しても、AIが「すみません、見つかりませんでした」と言ってくるケースだ。ファイルの海の中で方向感覚を失い、Tokenだけが消えていく。

CodeGraphはこの問題を根本から解決する。32,100 GitHub Star、MITライセンス。AIを賢くするのではなく、AIにコードベースの「地図」を渡すアプローチだ。

対象読者

• Claude Code、Cursor、CodexなどのAIコーディングツールを日常的に使う開発者
• 大規模プロジェクトでAIのToken消費とAPIコストに悩んでいる方
• コードベースの探索効率を上げ、AIコーディングのROIを改善したいエンジニア

🧠 仕組み：コード知識グラフの構築

CodeGraphがCursorのインデックスと根本的に異なるのは、その情報構造だ。

Cursorはベクトル埋め込みによるセマンティック検索を使う。質問をベクトル化し、コードベース内で類似度の高い断片をランキング形式で返す。これは探索には有用だが、決定的な弱点がある——構造を理解しない。関数間の呼び出し関係、モジュール間の依存関係、継承階層といった情報は、セマンティック検索では得られない。AIは「関連しそうな断片」を受け取り、それを手がかりに自分でファイルを開いて関係性を検証しなければならない。

CodeGraphは異なるアプローチを取る。tree-sitterを使ってソースコードをAST（抽象構文木）にパースし、言語ごとの抽出ルールでシンボル（関数、クラス、メソッド、インターフェース）とエッジ（呼び出し、インポート、継承、実装）を抽出する。

tree-sitterの採用は重要な設計判断だ。元々GitHubがAtomエディタ用に開発し、現在はNeovimのコア構文エンジンとして採用されているこのライブラリは、従来のコンパイラフロントエンドと異なり、**耐障害性（フォールトトレランス）**に優れている。コードに構文エラーがあっても部分的なASTを生成でき、解析速度も速い。実際の開発現場では、コードが常にコンパイル可能な状態とは限らない——CodeGraphがtree-sitterを選んだ所以だ。

抽出された構造データはすべてローカルのSQLiteデータベースに保存され、FTS5による全文検索インデックスが構築される。AI Agentが「この関数を呼び出しているのは？」と尋ねると、プロジェクト全体の探索ではなく、知識グラフへのクエリで応答する。1回のMCPツール呼び出しでエントリポイント・関連シンボル・コードスニペットが返却される。

🔄 他のコードインテリジェンスツールとの比較

Cursorのセマンティック検索は模糊探索に優れるが、呼び出し関係の確定情報は得られない。AIはランキング結果から自分でファイルを検証する必要がある。

**Gemini Code Assist（旧Google Cloud Code）**は強力だがクラウド依存。超大規模リポジトリの解析が可能な反面、コードがGoogleのサーバーにアップロードされる。規制対象業界やプロプライエタリコードを扱うチームには致命的な制約となる。

Sourcegraphは機能が豊富だが重い。サーバーデプロイ、インデクサー設定、インフラ維持が必要。CodeGraphは1つのバイナリとSQLiteファイルで完結する。

GitHub Copilotのコードベースインデックスはベータ段階で、クラウド処理のみ、限定的なロールアウト。

CodeGraphの差別化ポイントは**「ローカル＋軽量＋構造グラフ」**の組み合わせだ。サーバー不要、コードアップロード不要。そしてセマンティック検索のような曖昧な推薦ではなく、決定的な呼び出し関係を返す。

📊 ベンチマーク：7プロジェクト実測データ

7言語・7つの実在OSSプロジェクトで、Claude Opus 4.7（ヘッドレスモード claude -p）を使った比較テスト。同一タスク・同一モデルで、CodeGraphの有無のみを変数として4回実行し、中央値を報告。

プロジェクト	言語	ファイル数	Token削減	コスト削減	高速化	操作削減
VS Code	TypeScript	~10,000	78%	26%	52%	85%
Excalidraw	TypeScript	~640	90%	52%	73%	96%
Tokio	Rust	~790	86%	82%	71%	92%
Django	Python	~3,000	36%	12%	19%	53%
Alamofire	Swift	~110	64%	47%	48%	83%
OkHttp	Java	~645	13%	2%	31%	45%
Gin	Go	~110	34%	21%	27%	40%

平均：約35%コスト削減、57%Token削減、46%高速化、71%操作削減。

注目すべきパターン：

プロジェクト規模と効果が比例する。 VS Code（約10,000ファイル）ではTokenが280万→60.1万に激減。Excalidrawでは350万→34.4万。ファイル数が多いほど、地図なしの探索コストが指数関数的に増大する。

Rustプロジェクトで特に効果が大きい。 Tokioでは$2.41→$0.42と82%のコスト削減。Rustのモジュールシステム（mod、use、pub use、re-exportの多重階層）はAIの探索を特に消耗させる——CodeGraphがその迷路を一瞬で解決する。

小規模プロジェクトでは効果が限定的。 OkHttp（Java, 645ファイル）ではわずか13%のToken削減。Gin（Go, 110ファイル）でも34%。プロジェクトが小さいうちは、AIが直接ファイルを読み込んでもグラフを参照しても、大きな差が出ない。

重要なのは、これらがモデルの性能向上による成果ではないこと。Claude Opus 4.7は両方のテストで同一のモデルだ。削減されたTokenはすべて、機械的で反復的なファイル探索に浪費されていたものだ。

🔗 フレームワークルーティングの自動認識

Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin/chi/gorilla/mux、Axum/actix/Rocket、ASP.NET、Vapor、React Router、SvelteKitの14フレームワークのルーティングパターンをネイティブ認識。

各フレームワークでルーティングの宣言方法が異なる——Djangoは urlpatterns リストと path() 関数、Springは @GetMapping アノテーション、Railsは get '/x', to: 'users#index' のDSL——CodeGraphはそれぞれに専用の認識ルールを実装している。

「POST /api/usersを処理するハンドラは？」という質問に対し、CodeGraphはURLパターンから直接ハンドラ関数を特定する。ミドルウェアチェーン、ルートインクルード、デコレータスタックを一気に解決する。従来のようにルーティング設定ファイルを探索→ビュー関数を特定→という手順で、途中で間違えては戻る必要がない。

マイクロサービスや大規模APIサーフェスを横断的に扱うバックエンド開発者にとって、この機能だけでもインストールする価値がある。

⚡ 3層の自動同期：保存するだけ

CodeGraphのインデックス同期は3層設計で、手動リビルドの必要なツールより格段に使いやすい。

第1層：OSネイティブファイルウォッチャー。 macOS FSEvents、Windows ReadDirectoryChangesW、Linux inotify。各OSが提供する最下層のファイル変更通知メカニズム。ポーリングなし、CPU消費なし。ファイルを保存した瞬間にOSがCodeGraphに通知する。

第2層：デバウンスバッチング。 2秒の静寂ウィンドウ。リファクタリング時に5ファイルを連続保存しても、それらは1回の増分同期にまとめられる。ファイルごとの再構築は発生しない。

第3層：Stalenessフラグ＋再接続時高速同期。 未同期ファイルは明示的に「Stale」とマークされ、AI Agentは直接ファイルを読むべきかを判断できる。AIツールが再接続した際は、ファイルサイズと修正時刻の高速比較で変更分のみ同期。

結果：通常通りコードを書いているだけで、インデックスはバックグラウンドで静かに更新される。「インデックスを再構築するので待ってください」という瞬間はない。

🔒 100%ローカル動作

知識グラフは .codegraph/codegraph.db という単一のSQLiteファイルに保存される。クラウドコンポーネントなし、APIキー不要、データ送信ゼロ。プロプライエタリコードや規制対象データを扱うチームにとって、このアーキテクチャは導入障壁を大きく下げる。

💿 インストール

Node.js不要。1コマンドでインストール：

# macOS / Linux
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

npmでも可：npx @colbymchenry/codegraph

プロジェクト初期化：

cd your-project
codegraph init -i

-iフラグで初回の全量インデックスを実行。超大規模プロジェクト（10万ファイル以上）では初回に数分〜10分以上かかる場合があるが、一度限りのコスト。以降は増分同期のみ。

実用上の注意点：

• macOS：Xcodeコマンドラインツール（xcode-select --install）を先にインストールすること。未インストール時は互換モードにフォールバックし、5〜10倍低速
• デフォルト除外：node_modules、vendor、dist、build、target、.venv、.gitignoreエントリ、1MB超のファイル
• インデックスは .codegraph/codegraph.db に集約され、キャッシュファイルが散乱しない
• 対応AIツール：Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent、Gemini CLI、Antigravity、Kiro

⚠️ 現時点の制限

初期インデックス時間。 超大型コードベースでは初回に時間がかかる。tree-sitterの解析速度とディスクI/Oに依存する。

言語サポートの濃淡。 TypeScript、Python、Rust、Goは最も充実。Objective-Cは「部分サポート」。利用頻度の低い言語に依存するプロジェクトでは事前テストを推奨。

探索の補助であり推論の代替ではない。 CodeGraphが削減するのはコード探索のTokenであり、推論負荷の高いタスク（「なぜ遅いのか」「キャッシュ戦略を設計して」）には直接寄与しない。あくまでAIがコンテキストを素早く収集するための道具だ。

まとめ

AIコーディングツールの進化は、この1年「より賢いモデル」の開発に集中してきた。Claude vs GPT vs Gemini——各リリースがベンチマーク首位を競う。

しかしこれらのツールが日常の開発ワークフローに組み込まれるにつれ、別のボトルネックが浮上してきた。質問に答えるために50ファイルを読み込み、300万Tokenを消費し、2分半かかるモデルは、どれだけ賢くても気軽には使えない。摩擦が大きすぎ、コストが見えすぎる。

より賢明なアプローチは：適度に賢いモデルに正確な地図を渡し、10ファイルの読み込み、60万Token、1分で答えさせることだ。

CodeGraphはその地図を提供する。

GitHub: colbymchenry/codegraph