CodeGraph

@colbymchenry/codegraph v0.8.0 · semantic code intelligence for Claude Code, Cursor, Codex, OpenCode

1 — 概要
目的

CodeGraph は、AI コーディングエージェントが行う grep / glob / Read によるファイル走査を、事前に構築したコード知識グラフへのクエリに置き換えるツール。シンボル関係・呼び出しグラフ・構造情報をローカルの SQLite に保持し、MCP サーバー経由で Claude Code / Cursor / Codex CLI / OpenCode に公開する。

~35% コスト削減（7 OSS 中央値平均）
~70% ツール呼び出し削減
21 対応言語（Lua / Luau 含む）
100% ローカル（SQLite のみ）
データは外部に出ない。 API キー不要。インデックスはプロジェクト直下の .codegraph/codegraph.db に保存される。tree-sitter（WASM）で AST を解析し、FTS5 で全文検索を提供する。
主な機能

Smart Context

1 回のツール呼び出しでエントリポイント・関連シンボル・コード断片をまとめて返す。

Full-Text Search

FTS5 によりシンボル名をコードベース全体から即時検索。

Impact Analysis

変更前に callers / callees と影響半径をグラフ走査で把握。

Auto-Sync

OS ネイティブのファイルイベント（FSEvents / inotify 等）で保存後に増分同期。デバウンス 2 秒。

Framework Routes

Django / FastAPI / Express / Spring など 13 フレームワークのルート定義を route ノードとしてリンク。

codegraph affected

変更ファイルから import 依存を辿り、影響を受けるテストファイルを CI 向けに列挙。

2 — ベンチマーク（README 記載）
7 コードベース比較

Claude Opus 4.7 + Claude Code v2.1.145。各 OSS リポジトリでアーキテクチャ質問 1 件を、CodeGraph MCP あり / 空 MCP 設定なしで headless 実行。各条件 4 回の中央値を README が報告している。

コードベース 言語・規模 コスト トークン 時間 ツール呼び出し
VS Code TypeScript · ~10k files 35% 安 73% 少 41% 速 72% 少
Excalidraw TypeScript · ~600 47% 安 73% 少 60% 速 86% 少
Django Python · ~2.7k 34% 安 64% 少 59% 速 81% 少
Tokio Rust · ~700 52% 安 81% 少 63% 速 89% 少
OkHttp Java · ~640 17% 安 41% 少 36% 速 64% 少
Gin Go · ~150 22% 安 23% 少 34% 速 19% 少
Alamofire Swift · ~100 38% 安 59% 少 51% 速 77% 少
README の解釈: 大規模リポジトリほど効果が大きい。インデックス利用時は codegraph_context で領域を把握し codegraph_explore で関連ソースを一括取得するパターンが多く、ファイル Read がほぼ不要になる。小規模（Gin など）ではネイティブ検索との差が小さい。
3 — セットアップ
インストール 
npx @colbymchenry/codegraph

対話型インストーラが利用中のエージェント（Claude Code / Cursor / Codex CLI / OpenCode）を検出し、MCP 設定・指示ファイル・PATH への codegraph 登録を行う。

npx @colbymchenry/codegraph

# 非対話（CI / スクリプト）
codegraph install --yes
codegraph install --target=cursor,claude --yes
codegraph install --target=auto --location=local
codegraph install --print-config codex   # 設定スニペットのみ出力
  1. 上記を実行（または codegraph install）
  2. エージェントを再起動（MCP 読み込み）
  3. プロジェクトで codegraph init -i（.codegraph/ 作成 + 索引）
Explore エージェント向けルール（要約）

.codegraph/ があるプロジェクトでは、メインセッションから codegraph_explore / codegraph_context を直接呼ばない（大量ソースでコンテキストを消費するため）。探索質問は Explore エージェントに委譲し、プロンプトに CodeGraph 利用指示を含める。

メインセッションで直接使える軽量ツール: codegraph_search、codegraph_callers / codegraph_callees、codegraph_impact、codegraph_node。

4 — 動作の仕組み
アーキテクチャ 
flowchart TD
  AG[Claude Code / Cursor / Codex / OpenCode]
  MCP[CodeGraph MCP Server]
  DB[(SQLite + FTS5
.codegraph/codegraph.db)]
  TS[tree-sitter extraction]
  RES[Resolution + frameworks]
  WATCH[File watcher auto-sync]

  AG -->|MCP tools| MCP
  MCP --> DB
  TS --> DB
  RES --> DB
  WATCH -->|debounced incremental| TS
Extraction → Storage → Resolution → Auto-Sync
  • Extraction: tree-sitter で AST を解析。言語別クエリで関数・クラス・呼び出し・import などをノード/エッジ化。
  • Storage: SQLite + FTS5。プロジェクト内 .codegraph/ に保存。
  • Resolution: 呼び出し先定義・import 先・継承・フレームワーク固有パターンを解決。
  • Auto-Sync: MCP 起動中はソース変更を検知し、約 2 秒の quiet window 後に増分同期。
ソース構成（主要モジュール）
パス役割
src/extraction/tree-sitter 解析・言語別 extractors（Vue / Svelte / Liquid 等）
src/db/SQLite スキーマ・クエリ・native / WASM バックエンド
src/resolution/参照解決・フレームワークルート（Django, Express, Spring 等）
src/graph/グラフ走査（callers / callees / impact）
src/search/クエリパーサ・FTS 検索
src/context/タスク向けコンテキスト組み立て
src/mcp/MCP ツール定義・stdio トランスポート
src/sync/watcher.tsファイル監視・増分 sync
src/bin/codegraph.tsCLI エントリ
5 — MCP ツールと CLI
MCP ツール
ツール用途
codegraph_searchシンボル名で検索
codegraph_contextタスク向けコードコンテキスト生成
codegraph_explore関連ファイルのソース断片を一括取得（Explore エージェント向け）
codegraph_callers呼び出し元の列挙
codegraph_callees呼び出し先の列挙
codegraph_impactシンボル変更の影響範囲
codegraph_node単一シンボルの詳細（ソース付き可）
codegraph_files索引済みファイル構造（fs 走査より高速）
codegraph_statusインデックス統計・健全性
CLI（抜粋） 
codegraph init [path]              # 初期化（--index で同時索引）
codegraph index [path]             # フルインデックス（--force / --quiet）
codegraph sync [path]              # 増分更新
codegraph status [path]            # 統計表示
codegraph query <search>           # シンボル検索
codegraph context <task>           # AI 向けコンテキスト
codegraph affected [files...]      # 影響テスト列挙（--stdin 対応）
codegraph serve --mcp              # MCP サーバー起動

ライブラリ API（抜粋）

import CodeGraph from '@colbymchenry/codegraph';

const cg = await CodeGraph.init('/path/to/project');
await cg.indexAll({ onProgress: (p) => console.log(p.phase) });
const results = cg.searchNodes('UserService');
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true });
cg.watch();
cg.close();
6 — 設定・言語・トラブルシュート
.codegraph/config.json 
{
  "version": 1,
  "languages": ["typescript", "javascript"],
  "exclude": ["node_modules/**", "dist/**", "build/**", "*.min.js"],
  "frameworks": [],
  "maxFileSize": 1048576,
  "extractDocstrings": true,
  "trackCallSites": true
}
対応言語（README 一覧）

TypeScript / JavaScript / Python / Go / Rust / Java / C# / PHP / Ruby / C / C++ / Swift / Kotlin / Scala / Dart / Svelte / Vue / Liquid / Pascal・Delphi / Lua / Luau（Roblox 向け型・export type 対応）など。

よくある問題
症状対処（README）
CodeGraph not initializedcodegraph init を実行
索引が遅い / database is lockedcodegraph status の Backend が wasm なら npm rebuild better-sqlite3 で native 化
MCP 接続失敗索引済みか、MCP 設定パス、codegraph serve --mcp の手動確認
シンボル欠落保存後数秒待つか codegraph sync。言語対応・exclude 設定を確認
公式

License: MIT