CodeGraphガイド：AIエージェントのためのローカルコードナレッジグラフ

CodeGraphを理解しておくべき理由は、AIコーディングにおける現実的な失敗モードを解決するためです。エージェントはgrep、glob、ファイル読み込みを繰り返すことで、同じコード構造を何度も再発見するのにターンを浪費してしまいます。

1. CodeGraphを一言で言うと

CodeGraphは、MITライセンスのローカルファーストなコードインテリジェンスツールです。リポジトリを解析してファイル、シンボル、呼び出し、インポート、ルート、参照を含むSQLiteナレッジグラフを作成し、MCPを通じてAIコーディングエージェントにそのグラフを提供します。

A コードナレッジグラフ とは、コードのエンティティと関係性を格納したデータベースのことです。 MCP（Model Context Protocol）は、多くのエージェントが外部ツールを呼び出すために使用するツールプロトコルです。

2. 存在理由

The repo's README frames the problem around Claude Code exploration agents that repeatedly call grep, glob, Bash, and Read before answering architecture questions. That is expensive because file discovery is repeated per session and per task. CodeGraph moves discovery up front: parse once, store relationships locally, then let the agent query the graph.

The official docs site makes the same point in a smaller form: CodeGraph turns a codebase into a queryable local graph for AI coding agents, using tree-sitter parsing, MCP, and impact analysis. The npm package page repeats the README benchmark table and setup commands, which matters because the npm package is the main installation surface for many developers.

Status quo:
agent question
  -> grep/glob/read loop
  -> partial mental map
  -> answer
  -> next task repeats discovery

CodeGraph model:
codegraph init/index
  -> .codegraph/codegraph.db
  -> agent calls codegraph_context / trace / impact
  -> answer from graph-backed source context

3. メンタルモデル：5つの構成要素

CodeGraphは単一の検索コマンドとしてではなく、パイプラインとして評価する方が容易です。

+---------------------+      +----------------------+      +----------------------+
| scanner             | ---> | extractor             | ---> | resolver             |
| git + filesystem    |      | tree-sitter + helpers  |      | imports, calls,      |
| ignore rules        |      | language files         |      | frameworks, bridges  |
+---------------------+      +----------------------+      +----------+-----------+
                                                                      |
                                                                      v
                         +----------------------+      +----------------------+
                         | MCP tools            | <--- | SQLite graph         |
                         | context, trace,      |      | nodes, edges, files, |
                         | callers, impact      |      | FTS5 search          |
                         +----------------------+      +----------------------+

4. 最小限のエンドツーエンドの例

プロジェクトのREADMEには現在、短いインストール手順と、より詳細なクイックスタート手順が記載されています。 codegraph init -i はプロジェクトインデックスを構築しますが、エージェントがCodeGraphを呼び出すには、その前にMCPサーバーのエントリが必要です。

# 1. Install or run the interactive installer.
npx @colbymchenry/codegraph

# 2. Restart the agent after the installer writes its MCP config.

# 3. Build the project-local graph.
cd your-project
codegraph init -i

# 4. Check the index from the CLI.
codegraph status

# 5. Ask the agent a structural question.
# Example prompt:
"Use CodeGraph first. How does the auth request reach the database?"

Claude Codeを手動でセットアップする場合、READMEには以下の場所にJSON形式のMCPエントリが示されています。 mcpServers.codegraph。 ~/.codex/config.toml。

# Codex CLI manual shape, from the installer target.
[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]

5. 詳細解説：各レイヤーの仕組み

5.1 スキャナー：インデックス対象

スキャナーは可能な限りgitで管理されているファイルを使用し、gitプロジェクトではない場合や親レイアウトが無視されている場合は、ファイルシステムを走査して補完します。 node_modules、 dist、 target、 .venv、 Pods、および .next。

// Schema-level artifact: each indexed file becomes a row.
files(path, content_hash, language, size, modified_at, indexed_at, node_count, errors)

// Scanner-level artifact: ignored dependency/build directories are excluded
// before the graph becomes agent context.

個人的な見解：CodeGraphは、インデックスの範囲が単純で予測可能な場合に最も強力に機能します。

5.2 エクストラクター：シンボル優先、テキストは二の次

抽出処理は、構文木を生成するインクリメンタルパーサーであるtree-sitterを中心に構築されています。 src/extraction/languages/ それらの木を関数、メソッド、クラス、インターフェース、ルート、コンポーネント、変数、定数、モジュールといったノードに変換します。

nodes(
  id,
  kind,
  name,
  qualified_name,
  file_path,
  language,
  start_line,
  end_line,
  docstring,
  signature
)

個人的な見解：これが、CodeGraphが単なるベクトル検索のラッパーではない理由です。

5.3 リゾルバー：最も困難な部分

Static extraction finds references, but references are not useful until they resolve. CodeGraph's resolver handles import paths, name matching, framework routes, callback synthesis, dynamic-dispatch bridges, Swift to Objective-C bridging, React Native bridges, Expo modules, and framework-specific route shapes. Recent release notes show that much of the project's velocity is in this layer.

edges(
  source,
  target,
  kind,        -- calls, imports, contains, references, extends, implements...
  metadata,
  line,
  col,
  provenance
)

個人的な見解：リゾルバーの品質が、CodeGraphがリファクタリングにおいて安全に使用できるかを左右します。 0 callers 結果は、ツールがない場合よりも悪影響を及ぼす可能性があります。なぜなら、エージェントに対して「ライブコードがデッドコードである」という誤った情報を伝えてしまうからです。

5.4 SQLiteとFTS5：ローカルグラフ、ローカル検索

スキーマは、ノード、エッジ、ファイル、未解決の参照、およびプロジェクトのメタデータを、以下の場所にあるローカルのSQLiteデータベースに保存します。 .codegraph/codegraph.db。

CREATE VIRTUAL TABLE nodes_fts USING fts5(
  id,
  name,
  qualified_name,
  docstring,
  signature,
  content='nodes'
);

個人的な見解：この種のツールにとって、ローカルのSQLiteは適切なストレージの選択です。

5.5 MCPツール：エージェントの制御

CodeGraphは、search、context、callers、callees、impact、node、explore、status、files、traceというコンパクトなMCPツールセットを提供します。 src/mcp/server-instructions.ts、各エージェントの指示ファイルに複製されるのではなく、MCPのinitializeレスポンスを通じて読み込まれます。

個人的な見解：MCPのガイダンスは製品の一部である。

6. 私たちが間違っていたこと

最初、私はCodeGraphを単なるトークン圧縮プロジェクトとして扱っていた。

また、セットアップの手順は「インストールしてインデックス化するだけ」だと想定していた。

Bad assumption:
"init -i means my agent has CodeGraph"

Correct model:
"install wires MCP; init/index builds the repo graph"

7. 実践的なワークフローパターン

8. よくある間違いと失敗のパターン

GitHubのオープンなIssueは、ユーザーが実際の失敗を報告しているため、間違いを知るための最良の情報源です。これこそが導入において重要となります。

9. パフォーマンス、スケーリング、およびコストに関する注記

CodeGraphのREADMEでは、Claudeのヘッドレス実行において、CodeGraphの有無を比較した複数のオープンソースコードベースでのベンチマーク結果が報告されています。重要なのはその手法です。同一のアーキテクチャに関する質問、同一のリポジトリを使用し、一方にはCodeGraph MCPを有効化、もう一方には空のMCP設定を適用して、複数回の実行の中央値を算出しています。リポジトリによると、このベンチマークは2026年5月下旬のビルドにおいて、アダプティブ codegraph_explore サイジングを用いて再検証されたとのことです。

正直なところ、その解釈はヘッドラインが示すよりも限定的です。CodeGraphは、エージェントが本来であれば探索に多くのツール呼び出しを費やすようなケースで真価を発揮します。小規模なリポジトリや、ネイティブ検索が安価な単純なルックアップでは、その優位性は低下します。トークンオプティマイザーに関するRedditのスレッドでも同様の実践的な指摘がなされています。つまり、ツールが謳う節約トークン数だけでなく、ワークフロー全体を測定すべきだということです。

Use this local A/B shape:

Task: "How does request X reach handler Y?"
Run A: agent with CodeGraph MCP enabled
Run B: same agent, same repo, CodeGraph disabled

Measure:
- time to first useful answer
- file reads
- grep/bash/search calls
- accepted edits
- follow-up corrections
- total cost, if your client exposes it

10. CodeGraphの対象ユーザー

11. コミュニティの反応

一般的な反応は、有益な形で賛否が分かれています。

r/ClaudeCodeでのRedditの議論では、CodeGraphはリポジトリパッカー、コマンド出力圧縮ツール、メモリツール、MCPコードエクスプローラーといった、他のトークンおよびコンテキスト最適化ツールと並べて評価されました。

大規模なTypeScriptモノレポに関するr/ClaudeAIの別のスレッドでは、コンテキストに収まりきらないコードベースをどのように扱うかという議論がなされました。

12. 結論：CodeGraphを使う価値はあるか？

The best version of CodeGraph is boring: initialize the repo, let the agent call codegraph_context まず、以下を使用してください： trace フローに関する質問には、以下を使用してください。 impact 編集前に使用してください。

13. 全体像

CodeGraphは、プロンプトへの詰め込みからツールを活用したコンテキストへの移行という、より大きな潮流の中に位置しています。

この中間層が価値を持つのは、AIコーディングエージェントが単なるスニペット以上の情報を必要としているからです。

Context stack:
AGENTS.md / CLAUDE.md     -> rules and project intent
docs / package READMEs    -> human-authored architecture notes
CodeGraph                 -> local symbol and relationship graph
compiler / tests / linter -> correctness checks

The graph helps the agent navigate. It does not replace the rest.

14. よくある質問 (FAQ)

15. 用語集

16. すべてのソースとリンク

主要ソース

• colbymchenry/codegraph GitHubリポジトリ
• CodeGraph公式ドキュメントサイト
• npm package page for @colbymchenry/codegraph
• リサーチ時に確認した現在のリリースページ
• CHANGELOG.md

読み込まれたソースファイル

• src/index.ts - main CodeGraph class.
• src/db/schema.sql - nodes, edges, files, FTS5スキーマ。
• src/extraction/index.ts - スキャナー、デフォルトの除外設定、インデックス作成のオーケストレーション。
• src/mcp/tools.ts - MCPツールの定義。
• src/mcp/server-instructions.ts - エージェントの制御ガイダンス。
• src/sync/watcher.ts - ファイルウォッチャーおよび保留中ファイルのスタールネス（陳腐化）モデル。
• src/installer/targets/codex.ts - Codex CLIの設定構造。
• src/installer/targets/claude.ts - Claude Codeの設定構造。

GitHub Issues および Pull Requests

• Issue #644 - macOSにおけるファイルディスクリプタのリーク / ENFILEに関する報告。
• Issue #631 - READMEのセットアップ順序に関する混乱。
• Issue #629 - Svelte/TypeScriptにおけるバレル再エクスポートの未解決問題。
• Issue #628 - ウォッチモードにおけるリソースのガードレール。
• Issue #621 - MCP resources/list および prompts/list における欠落。
• Issue #613 - 大規模データベースでの MCP タイムアウト。
• Issue #634 - TypeScript の文字列リテラルによるサービス名がインデックス化されない問題。
• PR #632 - セットアップドキュメントおよび MCP ディスカバリーの修正。
• PR #643 - 提案された .codegraphignore override サポート。
• PR #603 - 組み込み SDK API の復元。

コミュニティソース

• r/ClaudeCode におけるトークンオプティマイザーの議論
• r/ClaudeAI における大規模コードベースのコンテキストに関する議論
• 慎重な一次読解速度に関するコメントが投稿された X のポスト
• CodeGraph を急成長中の AI リポジトリとして挙げた X のポスト

内部リンク

• Claude コンテキストガイド: Milvus を介したセマンティックコード検索 MCP
• ArcKitガイド：Wardley Mapping + Multi-AI Architecture Toolkit
• OpenAI Agents Python SDK：LangGraphおよびCrewAIとの詳細比較
• AntiGravity MCP：コンテキストスイッチの解消

17. ソース属性テーブル