Claude Code のコード探索を加速するOSS「codegraph」の仕組みと特徴

Claude Code や Cursor を業務で本格的に使い始めると、ほぼ必ず突き当たるのが「コード探索のトークン浪費」という壁です。数千ファイル規模のリポジトリで AI エージェントに調査タスクを任せると、Read と Grep を何十回も繰り返したあげく、結果として API コストと実行時間がふくらんでしまうという経験はないでしょうか。

特に難しいのは、こうした探索コストを下げる手段がすでに複数存在しており、Serena・CodeGraphContext・LSP ベースのカスタム MCP など、どれを選べばよいか比較情報が散らばっている点です。「とりあえず試す」には導入コストが高く、選定を間違えると後戻りに時間が取られます。

そこで本記事では、最近 GitHub で急速に注目を集めている OSS「colbymchenry/codegraph」を取り上げ、何を解決する OSS なのか、内部でどう動くのか、Serena など類似 OSS とどう違うのか、そして自分のリポジトリに導入すべきかどうかを判断するための基準までを一気通貫で整理します。

なお、本記事は動作検証を行わず、公式 README・リポジトリ内ドキュメント・各種解説記事に基づいて情報を整理しています。インストール手順や設定例はすべて公式情報からの引用として扱います。

codegraph とは何か

colbymchenry/codegraph は、Claude Code・Codex・Cursor・OpenCode といった AI コーディングエージェントのために設計された、事前索引型のコード知識グラフです。公式 README ではプロジェクトを次のように位置づけています。

Pre-indexed code knowledge graph for Claude Code, Codex, Cursor, and OpenCode — fewer tokens, fewer tool calls, 100% local

（出典: colbymchenry/codegraph README）

ひとことで言えば、AI エージェントがファイルを逐次読み込んで探索する代わりに、シンボル・呼び出し関係・影響範囲などを事前に索引化した知識グラフへクエリを投げる仕組みです。索引化と保存はすべてローカルで完結し、外部の DB やクラウドサービスは不要です。

GitHub での反響も大きく、2026 年 5 月時点で Star 数は 15,216、Fork は 841 を記録しています。主要言語は TypeScript で、ライセンスは MIT、リポジトリはアクティブに更新されています。

同名 OSS との混同に注意

「codegraph」という単語は、コード解析系 OSS のなかで一般名詞に近い扱いを受けており、同じ名前で別物のリポジトリが複数存在します。本記事で扱うのは colbymchenry/codegraph で、以下とは別プロジェクトです。

• CodeGraphContext/CodeGraphContext: KuzuDB または Neo4j をストレージとして使う Python ベースの知識グラフ。後ほどの比較セクションで詳しく扱います。
• techsavvyash/codegraph: SCIP インデクサと Neo4j を組み合わせた Code Property Graph 基盤で、エンタープライズ向けのトレーサビリティを志向するプロジェクト。

検索結果や記事中で「CodeGraph」と表記されているものを見かけたら、まずどのリポジトリを指しているのか確認することをおすすめします。

codegraph が解決する課題と効果

codegraph が狙うのは、AI コーディングエージェントが大規模リポジトリで陥りがちな「探索コストの肥大化」です。

AI エージェントがコードベース探索で抱える課題

Claude Code や Cursor のような AI エージェントは、リポジトリの全体像を把握していない初期状態から、Read と Grep を繰り返してコードを探索します。具体的には次のような問題が発生します。

• 数千ファイル規模のリポジトリでは、1 つの調査タスクで Grep や Read が数十回呼び出され、トークン消費が指数的に増加する
• 同じファイルを別のターンで何度も grep し直してしまい、コストと実行時間が冗長に膨らむ
• LSP（Language Server Protocol）は IDE 起動が前提のため、CLI ベースで動くエージェントから扱いにくい
• 既存のコード検索 MCP サーバーは LSP ベースのものが多く、言語ごとのセットアップが重い場合がある

codegraph は、これらの探索作業をエージェント任せにせず、事前にローカルへ索引化しておくことでアプローチを変えます。

公式ベンチマーク

公式 README およびメンテナの解説記事では、7 つの実プロジェクト（VS Code、Excalidraw、Django など）で測定した結果として、以下の数値が公表されています。

• 平均 API コスト削減: 35%
• トークン削減（中央値）: 59%
• ツール呼び出し削減（平均）: 70%
• 実行時間削減（中央値）: 49%

（出典: colbymchenry/codegraph README、および メンテナによる検証記事 "I Cut Claude Code Exploration Time and Costs by 90% With One Tool"）

メンテナ自身の別検証では、Claude Code の Explore エージェントでツール呼び出しが平均 92% 減、探索時間が 71% 短縮、VS Code リポジトリでは「52 ツール呼び出し → 3 呼び出し」という事例も紹介されています。数値はリポジトリ規模やタスク内容に依存するため一般化はできませんが、効果のオーダー感を示すには十分でしょう。

codegraph の仕組み

codegraph の中身は、公式リポジトリ内の CLAUDE.md に詳しく書かれています。ここではアーキテクチャの要点を整理します。

パイプライン全体像

codegraph は、おおよそ次のパイプラインで動作します。

ファイル → ExtractionOrchestrator (tree-sitter)
        → SQLite (.codegraph/codegraph.db)
        → ReferenceResolver → GraphQueryManager → ContextBuilder
        → MCP Server (codegraph serve --mcp)

（出典: colbymchenry/codegraph CLAUDE.md）

ポイントは大きく 3 つです。

1. 構文解析は tree-sitter で行う: 言語ごとの LSP ではなく、tree-sitter による軽量な構文木解析で関数・クラス・呼び出しなどを抽出します。これによって LSP 起動や言語別の重いセットアップが不要になります。
2. ストレージは SQLite + FTS5: 抽出した情報はプロセス内 SQLite に格納され、全文検索は SQLite の FTS5 拡張で実現されます。Neo4j や KuzuDB のような外部グラフ DB は使いません。
3. MCP 経由で AI エージェントへ公開する: 索引化したデータは MCP サーバー（codegraph serve --mcp）として提供され、Claude Code などのエージェントがツール呼び出しでクエリを投げる構造です。

ストレージとデータ保存先

索引データはプロジェクトルート直下の .codegraph/codegraph.db に保存されます。SQLite ファイル 1 つで完結するため、外部サービスへの通信は発生しません。社内コードを外部に送ることに制約がある B2B 案件や受託開発でも採用しやすい設計と言えます。

自動同期と差分更新

索引はプロジェクトのファイル変更を OS ネイティブのファイル監視機構（macOS の FSEvents、Linux の inotify、Windows の ReadDirectoryChangesW）で検知し、2 秒のデバウンスを挟んで差分更新します。.gitignore を自動的に尊重し、1MB を超えるファイルはスキップされる仕様です（colbymchenry/codegraph README）。

codegraph が提供する MCP ツール

codegraph は MCP サーバーとして 8 種類のツールを公開しています。それぞれ AI エージェントから直接呼び出せる API として設計されています。

（出典: colbymchenry/codegraph README）

汎用的な検索系の codegraph_search だけでなく、AI エージェントの典型タスクに合わせて「影響範囲解析」「タスク関連コード一括取得」のような専用ツールが用意されているのが特徴です。

フレームワーク認識ルーティング

codegraph はソースコードを構文解析するだけでなく、主要 Web フレームワークのルーティング定義も自動で抽出します。対応フレームワークは Django・Flask・FastAPI・Express・NestJS・Laravel・Rails・Spring・Gin・Axum・ASP.NET・Vapor・React Router・SvelteKit など 14 種類以上で、URL パスとハンドラの対応関係をグラフ上で扱えるようになります。

API 改修や URL 設計の見直しで「このエンドポイントを変更したらどこに影響するか」を AI エージェントに調べさせるとき、フレームワーク認識ルーティングはとくに効きます。

対応エージェント・言語・動作環境

codegraph を導入する前に、自分の利用環境と要件が合うかを確認しておきましょう。

対応 AI エージェント

公式が動作確認している AI エージェント・エディタは次の 5 つです。

• Claude Code
• Cursor
• Codex CLI
• opencode
• Hermes Agent

インストール時に対話的にエージェントを選択すると、それぞれの設定ファイルが自動で書き込まれます。

（出典: colbymchenry/codegraph README）

対応プログラミング言語

対応言語は 19 種類以上で、Web 系・モバイル系・システム系の主要言語を一通りカバーしています。

TypeScript / JavaScript / Python / Go / Rust / Java / C# / PHP / Ruby / C / C++ / Swift / Kotlin / Scala / Dart / Svelte / Vue / Liquid / Pascal/Delphi / Lua / Luau

動作要件と既知の制約

導入前にとくに注意したいのが Node.js のバージョン要件です。公式の package.json および CLAUDE.md には、サポート範囲が >=18.0.0 <25.0.0 と明記されており、Node 25 系では起動が拒否されます。

"engines": {
  "node": ">=18.0.0 <25.0.0"
}

（出典: colbymchenry/codegraph CLAUDE.md）

nvm などで Node のバージョンを切り替える運用をしている場合は問題になりにくいものの、開発環境を Node 25 に統一済みのチームでは追加の調整が必要です。そのほか以下の制約も覚えておきましょう。

• .gitignore を自動尊重するため、意図的に除外しているテストデータ等は索引対象外
• 1MB を超えるファイルは自動的にスキップ
• tree-sitter ベースのため、型推論や動的ディスパッチを含む影響範囲解析は LSP ベースより浅くなる傾向がある

導入手順（公式ドキュメントベース）

ここでは公式 README に記載されたインストール手順を引用形式で整理します。実行コマンドはすべて colbymchenry/codegraph README からの抜粋です。

インストール方法

公式は 2 種類のインストールパスを提示しています。

# 方法 A: ワンライナーで導入
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# 方法 B: npm パッケージから導入
npx @colbymchenry/codegraph
# または
npm i -g @colbymchenry/codegraph

（出典: colbymchenry/codegraph README / npm: @colbymchenry/codegraph）

CI や複数マシンへの展開を行う場合は、npm 経由でバージョン固定する方法が扱いやすいでしょう。

プロジェクト索引化と MCP サーバー起動の流れ

インストール後は、AI エージェントとの統合と索引化を順に行います。

# エージェント統合（対話型）
codegraph install

# 明示的にターゲット指定
codegraph install --target=cursor,claude --yes

# プロジェクト索引化（プロジェクトルートで実行）
cd your-project
codegraph init -i

# MCP サーバー起動（通常はエージェント側から自動起動される）
codegraph serve --mcp

（出典: colbymchenry/codegraph README）

公式 README によれば、VS Code 全体（3,251 ファイル / 119,675 ノード / 116,424 エッジ）を約 30 秒で索引化できるとされています。エージェントから利用する際は、codegraph serve --mcp を直接起動するより、codegraph install で書き込まれた MCP 設定経由で自動起動させる運用が標準です。

Serena など類似 OSS との違い

ここからが本記事の本題とも言えるパートです。AI エージェントのコード探索を加速する OSS は他にも存在するため、それぞれと codegraph の棲み分けを整理します。

codegraph と Serena（oraios/serena）の比較

Serena は、LSP（Language Server Protocol）をバックエンドにして AI エージェント向けにコードナビゲーションを提供する OSS です。codegraph と並んで議論されることが多い存在です。

（Star 数は 2026 年 5 月時点。出典: colbymchenry/codegraph / oraios/serena）

棲み分けは次のように整理できます。

• codegraph が向くケース: セットアップを軽くしたい、AI エージェントの探索コスト削減を最優先したい、多言語が混在する中規模〜大規模リポジトリ
• Serena が向くケース: 型に厳格な静的言語（Java / Kotlin / TypeScript 等）で型解決を含む深い解析が必要、IDE 機能と同等の参照解決を AI エージェントから利用したい

codegraph と CodeGraphContext の比較

同じく「CodeGraph」系で混同しやすい CodeGraphContext との違いも整理しておきます。

（出典: colbymchenry/codegraph / CodeGraphContext/CodeGraphContext）

CodeGraphContext は KuzuDB / Neo4j 上で Cypher 風のグラフクエリを書きたい場面で強みを発揮します。一方で、AI エージェントから扱う MCP サーバーとしての完成度や、AI 探索コストに直結したベンチマーク提示の手厚さでは codegraph に分があります。

techsavvyash/codegraph との混同回避

同じく「codegraph」を名乗る techsavvyash/codegraph は、SCIP インデクサ + Neo4j を使った Code Property Graph 基盤で、エンタープライズ向けのトレーサビリティを志向するプロジェクトです。AI エージェントのコード探索を加速する目的の colbymchenry/codegraph とは、ターゲット利用者も思想も大きく異なります。

検索や記事タイトルで「codegraph」とだけ書かれている場合、どのリポジトリを指しているのかを GitHub の owner 名まで確認することをおすすめします。

codegraph の導入を判断する基準

ここまでの整理を踏まえ、codegraph を「自分のリポジトリに導入すべきかどうか」の判断軸をまとめます。

導入が効きやすいケース

以下の条件のいずれか、あるいは複数に当てはまるリポジトリでは、codegraph の効果が出やすいでしょう。

• リポジトリ規模が大きい: ファイル数が概ね 1,000 を超え、AI エージェントの Read / Grep 連発でトークン消費が無視できないレベルに達している
• Claude Code / Cursor / Codex CLI を日常的に運用している: 公式 README の数値がそのまま自分の運用にスケールしやすい
• 多言語が混在している: フロントエンド（TypeScript / Vue / Svelte）+ バックエンド（Python / Go / Rust）といった構成で、tree-sitter ベースの一括索引化が有利
• Node.js 18 〜 24 系を許容できる: 既存の開発環境やビルド環境と衝突しない
• 外部にコードを出せない: 社内・受託案件などで、100% ローカル完結が要件になっている

別の選択肢を検討したいケース

逆に、次のような条件のリポジトリでは codegraph 単体では物足りない可能性があります。

• 型解析の正確性が決定的に重要: ポリモーフィズムや動的ディスパッチを含む影響範囲解析を厳密に行いたい場合、LSP ベースの Serena や言語固有ツールのほうが向く
• Node 25 系を必須としている: 開発環境を最新 Node に固定済みで、ダウングレードできない場合
• 既存のグラフ DB 基盤を活用したい: Neo4j / KuzuDB 上で独自クエリを書きたいなら、CodeGraphContext や techsavvyash/codegraph のようなグラフ DB ベースのアプローチが選択肢になる
• IDE 機能の代替として AI エージェントから参照したい: 「go to definition」「find references」を IDE と同等の精度で使いたい場合は LSP ベースのツールが優位

判断に迷うときは、まず手元で最も大きい単一リポジトリに対して「Read / Grep の呼び出し回数がどの程度になっているか」「型情報が必須の調査タスクが多いか」を 1 週間ほど観察してから決めると、ミスマッチが起きにくくなります。

まとめ

本記事では、AI コーディングエージェント向けのコード知識グラフ OSS「colbymchenry/codegraph」を、仕組み・MCP ツール・類似 OSS との違い・導入判断基準の 4 つの観点から整理しました。要点は次のとおりです。

• codegraph は事前索引型のコード知識グラフで、AI エージェントの探索操作（Read / Grep 連発）を MCP クエリに置き換えることでトークンとツール呼び出しを大幅に削減する OSS です。公式ベンチマークでは API コスト 35% 減・トークン 59% 減・ツール呼び出し 70% 減という数値が公表されています。
• 仕組みは tree-sitter + SQLite + FTS5 + MCP という軽量構成で、外部 DB やクラウドは不要です。索引は .codegraph/codegraph.db にローカル保存され、ファイル監視で自動的に差分更新されます。
• Serena との棲み分けは「セットアップの軽さ + AI 探索コスト削減」vs「LSP による深いセマンティクス」で、CodeGraphContext との棲み分けは「ゼロ依存のローカル完結」vs「グラフ DB ネイティブのクエリ表現力」です。同名の techsavvyash/codegraph とは目的が異なるため混同に注意が必要です。
• 導入判断の軸は、リポジトリ規模・利用エージェント・対応言語・Node バージョン・型解析の厳密さの 5 点です。Node 25 系を必須としている、または型解析の正確性が極めて重要なリポジトリでは別の選択肢を検討する価値があります。

次のアクションとしては、まず GitHub リポジトリ と npm パッケージページ で最新のバージョン情報と要件を確認し、自分のリポジトリの規模・利用エージェント・Node バージョンと照らし合わせてみてください。本記事で整理した判断軸に沿って情報を当てはめれば、導入の是非はかなり明確に絞り込めるはずです。

画像指示

• アイキャッチ推奨クエリ: code graph network visualization blue
• 本文内画像:

  挿入位置（セクション見出し）	検索クエリ	備考
  codegraph の仕組み	code knowledge graph architecture diagram	アーキテクチャ図
  Serena など類似 OSS との違い	software tools comparison chart	OSSツール比較