Codegraphx (cgx)

CodeGraphX (CGX)

ウェブサイト： techcraze00.github.io/CodeGraphX · npm： codegraphx

CodeGraphX (CGX) は、AI コーディングエージェントと人間の開発者向けの、ローカルでトークン効率に優れたコードベースグラフエンジンです。Tree-sitter でソースコードを解析し、SQLite に双時的なセマンティックグラフを保存して、CLI と MCP サーバー経由で提供します。そのため、エージェントは「この関数を変更したら何が壊れるか」と質問し、50 個のファイルを読む代わりに、数百トークンで正確な答えを得られます。

---

CodeGraphX とは？

定義 — CodeGraphX はコードインテリジェンス層です。コードベース内のシンボル（関数、クラス、変数）、それらの関係（calls、called_by、imports、inherits、言語をまたぐ API_CALLS）、および時間とともにどのように変化するかを表す、永続的でクエリ可能なグラフです。

どのような種類のツールですか？ Language Server（LSP）やコード検索インデックスと同じ系統ですが、LLM エージェント向けに特化して設計されています。

• Language Server は、エディターに対して一度に 1 つのシンボルの「定義へ移動」を提供します。
• grep／埋め込み検索はテキストを検索しますが、構造は検索しません。
• CodeGraphX は、構造に基づくリポジトリ全体の推論に関する質問 — 影響範囲、依存関係の循環、言語をまたぐコントラクト、「このシンボルはそもそも存在するのか？」など — に答え、その結果をエージェントがそのままコンテキストに取り込めるトークン最適化形式でシリアライズします。

解決する中核的な課題 — AI コーディングエージェントは、コードベースを再発見するためにトークン予算の大半を費やしています。ファイルを開き、スクロールし、grep し、セッションのたびに同じモジュールを読み直します。CodeGraphX は一度インデックスを作成し、グラフからこれらの質問に答えるため、エージェントはトークンをスキャンではなく推論に使えます。

---

役立つ理由（トークンのコスト）

エージェントのあらゆるアクションにはトークンコストがかかります。よくある質問を考えてみましょう。「validateInput を変更すると、何が壊れますか？」

方法	エージェントの処理	おおよそのコンテキストコスト
CGX なし	validateInput を grep し、候補ファイルを約 15～50 個開いて、それぞれを読んで呼び出し箇所を追跡します	数万トークン、ツールとの往復が数回
CGX あり	explain_impact({ symbol_name: "validateInput" }) → 上流の呼び出し元と下流の呼び出し先をまとめた小さな JSON が 1 つ返されます	数百トークン、往復 1 回

CGX はグラフを JSON ではなく TOON（Token-Oriented Object Notation）でシリアライズするため、節約効果はさらに大きくなります。TOON は、JSON のトークン数の大半を占める繰り返しのキーや波括弧を取り除く、コンパクトな表形式のエンコーディングです。

正直な説明： 以下の精度の数値は、手作業でラベル付けしたコーパスを基準に測定したものです。上記のトークン数は、一般的なエージェントの動作を示すための 例示的なモデル であり、ラボで測定したベンチマークではありません。正確な比率は、リポジトリやエージェントによって異なります。効果をもたらすのは、仕組み（多数のファイルを読む代わりに、対象を絞ったグラフクエリを 1 回実行すること）です。

CGX の効果が特に大きい場面：

• 「すべて読む」のが現実的ではない、大規模なリポジトリや不慣れなリポジトリ。
• 長時間にわたるエージェントのセッション（エージェントが再構築する必要のないキャッシュとして、グラフを利用できます）。
• 呼び出しグラフがファイルをまたいで追跡できない、複数言語のスタック（React ⇄ Express/Flask/FastAPI）。
• 影響範囲や、使用されていないインポート・壊れたインポートの検出が重要となる、リファクタリングやレビュー。

---

すべての機能

機能	内容
🧠 シンボルグラフ	calls、called_by、imports、inherits のエッジを持つ、すべての関数／クラス／メソッド
⚡ O(1) シンボル検索	Bloom フィルターが DB にアクセスすることなく、probable_yes／definite_no を返します
💥 影響範囲の追跡	SQL CTE によって、上流（呼び出し元）／下流（呼び出し先）の影響範囲を再帰的に追跡します
🌉 言語をまたいだリンク	フロントエンドの fetch／axios 呼び出しとバックエンドのルートを照合し、信頼度スコア付きの API_CALLS エッジとして記録します
🕑 二時点履歴	追記専用のグラフにより、任意のコミット時点 のコードベースをクエリできます。データは一切削除されません
🩺 診断	見つからない／解決できないインポート、解決できない呼び出し先、循環依存、構文エラーを報告します
✅ タスクの検証	タスクの説明を、コミットで実際に変更されたシンボルと比較し、テストされていない追加を検出します
🔀 セッション／ブランチの差分	HEAD またはブランチと比較した、追加／削除／変更されたシンボルの構造的な要約
🌐 インタラクティブなダッシュボード	ブラウザー上に、コードベース全体の D3.js フォースグラフを表示します
📦 TOON 成果物	エージェントのコンテキストに注入するための、トークン最適化済みグラフとファイルインデックスのエクスポート
🔐 100％ローカル	クラウドなし、テレメトリーなし、ネットワーク通信なし。コードがマシンの外に出ることはありません
🤖 MCP サーバー	MCP 互換エージェントで利用できる 6 つのツールを公開し、設定不要の自動インデックス作成に対応します

---

このプロジェクトで使用されている技術

レイヤー	技術
解析	言語ごとの文法（tree-sitter-python、-javascript、-typescript、-html、-css）を備えた Tree-sitter
ストレージ	Kysely の型安全なクエリビルダーを介した、better-sqlite3 による SQLite（デフォルト）または Postgres（pg）
エージェントプロトコル	stdio 経由の Model Context Protocol SDK（@modelcontextprotocol/sdk）
確率的検索	bloom-filters
トークン最適化出力	TOON（@toon-format/toon）
CLI	Commander と、対話形式のセットアップに使用する @clack/prompts
ファイル監視	chokidar
ランタイム	Node.js ≥ 18、CommonJS

---

対応言語

言語	拡張子	抽出対象
Python	.py	関数、クラス、呼び出し、インポート（パッケージ相対の . / .. を含む）、Flask/FastAPI のルート
JavaScript	.js, .jsx	関数、クラス、アロー関数、呼び出し、インポート/require、ローカルバインディング、fetch/axios の呼び出し、Express のルート
TypeScript	.ts, .tsx	JS と同様に、TypeScript 固有の宣言も抽出
HTML	.html	要素 / 構造シンボル
CSS	.css	セレクター（クラス、ID）

---

インストール

# Global (recommended)
npm install -g codegraphx

# Or per-project
npm install --save-dev codegraphx

# Verify
codegraphx --version        # 1.2.4

CLI は codegraphx、cgx、および MCP エントリーポイントの cgx-mcp として利用できます。

---

クイックスタート

cd your-project

# 1. Index the codebase → writes .codegraphx/ + .codegraphx.db
cgx init

# 2. Ask questions
cgx query authenticateUser                       # where is it, what calls it, what it calls
cgx impact authenticateUser --direction downstream --depth 5
cgx impact authenticateUser --direction upstream
cgx stats                                        # files / symbols / edges
cgx doctor                                       # health report

# 3. Optional live view
cgx watch                                        # re-index on file change
cgx dashboard                                    # open the D3 graph in a browser

再スキャンでは全面的に書き換えます。 各 cgx init / cgx scan は .codegraphx/ を最初から再構築します。ディスクから削除されたファイルはグラフから除去され、古い成果物は消去され、データベースでは削除されたシンボルが時間的にクローズされるため、グラフは常に作業ツリーと一致します。変更されていないファイルはキャッシュから引き続き提供されるため、高速さを維持できます。

CLI コマンドリファレンス

コマンド	目的
cgx setup	MCP サーバーとスキルをコーディング CLI に接続します（下記参照）
cgx init / cgx scan	コードベース全体をインデックス化します
cgx query <symbol>	シンボルのファイル、型、calls、called_by を表示します
cgx impact <symbol> [--direction up/downstream] [--depth N]	影響範囲をたどります
cgx doctor [--json] [--strict] [--no-calls]	インポート、呼び出し、循環、構文を診断します
cgx stats	ファイル / シンボル / 関数 / クラス / エッジの件数を表示します
cgx watch	ファイルの変更に応じてグラフを自動更新します
cgx dashboard	インタラクティブな codegraph.html を開きます
cgx git-hook <install|remove>	post-commit / pre-push で自動スキャンします
cgx session summary [--branch <b>]	現在のセッションの構造的な変更概要を表示します
cgx verify --task <desc> --commit <hash>	タスクとコミットを照合する検証情報を表示します

---

MCP サーバー（AI エージェント向け）

CodeGraphX には、6 つのツールを公開する MCP stdio サーバーが含まれています。セットアップ不要： 事前にスキャンする必要はありません。プロジェクトで初めてサーバーを起動すると、バックグラウンドでコードベースのインデックス化を開始します。インデックス化中は get_graph_status が "indexing" を返し、"ready" になるとすべてのツールを利用できます。

利用可能な MCP ツール

ツール	説明	パラメーター
get_graph_status	準備状況：indexing / ready / error とファイル数	—
list_files	インデックス化されたファイルを一覧表示します	filter?: string
check_symbol_exists	O(1) の Bloom 検索 → probable_yes / definite_no	name: string
explain_impact	シンボルの上流の呼び出し元と下流の呼び出し先	symbol_name: string
verify_task	タスクの説明とコミットの実際の変更を比較します	task_description: string、commit_hash?: string
get_session_diff	現在のセッション / ブランチの構造的な概要	branch?: string（デフォルトは HEAD）

エージェントのワークフロー例

User: "What breaks if I change the validateInput function?"

Agent (via MCP):
  1. check_symbol_exists({ name: "validateInput" })   → { exists: "probable_yes" }
  2. explain_impact({ symbol_name: "validateInput" })
       → { used_by_upstream: ["src/auth.js::login"],
           breaks_downstream: ["src/api.js::handleRequest"] }

Result: exact answer, no file scanning.

プロジェクトルートの指定

サーバーは起動したディレクトリをインデックス化します。クライアントがプロジェクトルートを設定しない場合は、明示的に指定してください。

cgx-mcp --project-root /path/to/project
# or
CGX_PROJECT_ROOT=/path/to/project cgx-mcp

---

セットアップ — どれくらい簡単ですか？

1 つのコマンド

cgx setup

インストール済みのコーディング CLI を自動検出し、設定するものを複数選択できるので、それぞれを接続できます。設定を手作業で編集したり、絶対パスを探したりする必要はありません。利用可能な場合は各 CLI のネイティブコマンドを使用し、そうでない場合は JSON ファイルにフォールバックして MCP サーバーを登録します。絶対 Node パスとバンドル済みの cgx-mcp を使用するため、グローバルインストールとローカルインストールのどちらでも動作します。また、CGX の使用スキル / 手順を各 CLI の形式でインストールします。

cgx setup                                   # interactive multi-select
cgx setup --agents claude,gemini --yes      # non-interactive (CI / scripted)
cgx setup --project                         # register for the current repo only

登録はデフォルトでユーザー / グローバル単位なので、一度実行すればすべてのプロジェクトで機能します。cgx-mcp は、CLI の起動場所に応じてプロジェクトを解決します。既存の設定は保持され、初回の編集前にバックアップが作成されます。

対応しているコーディングエージェント CLI

エージェント	検出方法	MCP 登録	スキル／指示
Claude Code	PATH 上の claude または ~/.claude	claude mcp add → ~/.claude.json または .mcp.json	~/.claude/skills/cgx/SKILL.md
Gemini CLI	PATH 上の gemini	~/.gemini/settings.json または .gemini/settings.json	GEMINI.md（コンテキストファイル）
Antigravity CLI	PATH 上の agy	~/.gemini/config/mcp_config.json または .agents/mcp_config.json	~/.gemini/skills/cgx/SKILL.md または .agents/skills/cgx/SKILL.md
OpenCode	PATH 上の opencode	opencode mcp → 設定ファイル	AGENTS.md
Cursor	~/.cursor が存在する	~/.cursor/mcp.json または .cursor/mcp.json	.cursor/rules/*.mdc

その後、任意のプロジェクトで CLI を開き、"use cgx to explore this codebase." と入力します。

cgx setup が動作しない場合 — 手動でのセットアップ

MCP エントリーの形式は常に同じです。バンドルされている cgx-mcp を、node の絶対パスを指定して実行します（クライアントによってはシェルの PATH を引き継がないためです）。次のコマンドで確認できます。

which node                    # e.g. /usr/local/bin/node
which cgx-mcp                 # e.g. /usr/local/lib/node_modules/codegraphx/bin/cgx-mcp

Claude Code — プロジェクトから実行します。

claude mcp add codegraphx -- npx -y -p codegraphx cgx-mcp

または .mcp.json：

{ "mcpServers": { "codegraphx": { "command": "npx", "args": ["-y", "-p", "codegraphx", "cgx-mcp"] } } }

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。プロジェクトディレクトリがないため、ルートを設定します。

{ "mcpServers": { "codegraphx": {
  "command": "npx",
  "args": ["-y", "-p", "codegraphx", "cgx-mcp", "--project-root", "/path/to/project"]
} } }

Gemini CLI — .gemini/settings.json（node の絶対パスを使用します）：

{ "mcpServers": { "codegraphx": {
  "command": "/ABSOLUTE/PATH/TO/node",
  "args": ["/ABSOLUTE/PATH/TO/node_modules/codegraphx/bin/cgx-mcp"],
  "cwd": "/ABSOLUTE/PATH/TO/PROJECT"
} } }

Antigravity CLI（agy）— ファイルのみで設定し、ネイティブコマンドはありません。グローバル設定の ~/.gemini/config/mcp_config.json またはプロジェクトごとの .agents/mcp_config.json：

{ "mcpServers": { "codegraphx": {
  "command": "/ABSOLUTE/PATH/TO/node",
  "args": ["/ABSOLUTE/PATH/TO/node_modules/codegraphx/bin/cgx-mcp"]
} } }

Cursor／Windsurf／その他の MCP クライアント — ~/.cursor/mcp.json（またはプロジェクトの .cursor/mcp.json）を使用します。構造は同じです。cwd をプロジェクトルートに設定してください。

接続を確認するには：

# inside the CLI
/mcp list           # should show: codegraphx — Connected (6 tools)

# or drive the server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx -y -p codegraphx cgx-mcp

それでも接続できない場合：

1. npx ではなく、node の絶対パスを使用します。
2. cwd／--project-root がプロジェクトと正確に一致していることを確認します。
3. プロジェクト単位の Gemini 設定を使用する場合は、gemini trust を実行します。
4. 標準エラー出力を確認します：node /path/to/cgx-mcp 2>&1 | head -20。

---

アーキテクチャ

データフロー

Source files
   → parser.js            Tree-sitter, one adapter per language
   → entities.js          SymbolEntity / FileEntity / EdgeEntity (the domain model)
   → edgebuilder.js       CALLS / IMPORTS / INHERITS edges
   → cross-language-linker.js   fetch/axios ⇄ Express/Flask/FastAPI  →  API_CALLS edges
   → scanner.js           orchestrates a full scan; writes DB + .codegraphx/ artifacts
   → store/sql-store.js   Kysely ORM — append-only bi-temporal graph (SQLite / Postgres)

スキャン後は、プロジェクトルートにある .codegraphx.db が信頼できる唯一の情報源になります。.codegraphx/ ディレクトリには、派生アーティファクトである codegraph.html（ダッシュボード）、codegraph-graph.json（D3）、codegraph.toon と file_index.toon（トークン最適化済み）、symbols.bloom、cache.json が格納されます。

双時点・追記専用ストレージ

files、symbols、edges の行が削除されることはありません。各行には valid_from_commit_id と valid_to_commit_id が含まれ、後者が NULL の場合は「現在有効」を意味します。シンボルを編集すると、古い行を閉じて新しい行を挿入します。ファイルを削除すると、その行は時間的にクローズされます。これにより、履歴を失うことなく、CGX は「コミット X 時点でグラフがどのような状態だったか」を回答でき、セッション／ブランチの差分やタスクの検証にも活用できます。

主要モジュール

モジュール	役割
src/parser.js	ファイルを言語アダプターに振り分けます。declaredSymbols、imports、calls を返します
src/languages/*	言語ごとの Tree-sitter アダプター（python、javascript、typescript、html、css）
src/entities.js	SymbolEntity、FileEntity、EdgeEntity、Snapshot のドメインモデル
src/edgebuilder.js	解析された参照から構造エッジを構築します
src/cross-language-linker.js	フロントエンドとバックエンドの境界をまたぐ、信頼度スコア付きの API_CALLS エッジ
src/resolver.js	正規インポートリゾルバー（JS の ./／../、Python のパッケージ相対パス、ドット区切りパス）
src/scanner.js	runScan() — インデックス作成のエントリーポイントです。全置換のセマンティクスを持ち、mcpMode では負荷の高い出力をスキップします
src/store/sql-store.js	SqlGraphStore — すべての DB 読み取り／書き込みを処理します。traceImpact は再帰 SQL CTE を使用し、pruneDeletedFiles を提供します
src/store.js	GraphStore — スキャナーと doctor が使用する、メモリー内および cache.json のレイヤーです
src/doctor.js	診断エンジン（インポート／呼び出し／循環／構文）
src/verifier.js	タスクとコミットの検証エビデンス
src/sdk/index.js	IntelligenceSDK — CGX を組み込むためのプログラム API
src/server/mcp-server.js	CodeGraphXServer — MCP stdio サーバー
src/setup/*	cgx setup オーケストレーターと CLI ごとのアダプター
src/db/*	Kysely db インスタンスとマイグレーション（切り替えるには DB_DIALECT=postgres と DATABASE_URL を設定します）

---

ベンチマークと精度

CGX は、コードを読む代わりに信頼して使えることを目指しています。そのため、すべてのシンボル、エッジ、言語間リンク、インポートサイクルが既知の、手作業でラベル付けされた ゴールデンコーパス（tests/golden/）に対してグラフを評価します。同じハーネスが CI（tests/golden/accuracy.test.js）のゲートとしても使われ、パーサーのリグレッションがあるとビルドが失敗します。

抽出精度（厳選されたコーパス：3 個のフィクスチャ、9 個のファイル、20 個のシンボル）：

カテゴリー	適合率	再現率	F1
シンボル	100%	100%	100%
構造エッジ（CALLS／IMPORTS／INHERITS）	100%	100%	100%
言語間 API リンク	100%	100%	100%
エンドポイントのタグ付け	100%	100%	100%

推論と決定性：

チェック	結果
影響範囲の追跡（到達可能な集合との完全一致）	4/4（100%）
循環インポートの検出（再現率）	1/1（100%）
循環インポートの誤検知	0
再スキャン間の決定性	はい

スループット： コーパスで約 82 ファイル／秒、約 183 シンボル／秒（全スキャンで約 110 ms）。

BENCHMARK.md と benchmark-results.json を再現・再生成するには：

npm run benchmark

これらの数値は、制御されたコーパスでの抽出の正確性を検証するものであり、すべての言語構文を網羅していることを示すものではありません。ground-truth.json を含むフィクスチャを tests/golden/<name>/ の下に追加して、対象範囲を広げてください。

---

言語間インテリジェンス

スキャン中、CGX はクライアントが行う HTTP リクエストとサーバーが公開するルートを抽出し、それらを信頼度スコア付きの API_CALLS エッジとして対応付けます。

fetch('/api/users')        ──API_CALLS(0.9)──▶  app.get('/api/users', listUsers)   [Express]
axios.post('/api/orders')  ──API_CALLS(0.9)──▶  @router.post('/api/orders')        [FastAPI]
fetch(`/api/users/${id}`)  ──API_CALLS(0.7)──▶  @app.route('/api/users/<id>')      [Flask]

• フロントエンド： fetch(...)（method を含む）、axios.get/post/...、axios({ url, method })。
• バックエンド： Express／router、Flask（@app.route(..., methods=[...])）、FastAPI（@router.get、@app.post、…）。
• 信頼度： パスとメソッドが完全一致する場合は 0.9、パスが完全一致しメソッドが異なる場合は 0.75、パラメーター化されたパスとメソッドが一致する場合は 0.7、パラメーター化されたパスでメソッドが異なる場合は 0.55 です。パスパラメーター（:id、{id}、<int:id>）は最初に正規化されるため、/api/users/${id} は /api/users/{user_id} にリンクされます。

ルートハンドラーには endpoint オントロジーマーカーが付与され、explain_impact は API_CALLS エッジをたどります。そのため、"このバックエンドハンドラーを呼び出すのは何か？" という問い合わせに対して、言語の境界を越えたフロントエンドの呼び出し元が返されます。

---

セキュリティとプライバシー

• ✅ 100%ローカル — ネットワーク通信、テレメトリー、クラウド同期はありません。
• ✅ 読み取り専用 — CGX がソースコードを変更することはありません。
• ✅ 静的解析のみ — コードは解析されますが、実行されることはありません。
• ✅ 除外設定が可能 — .codegraphxrc で機密性の高いパスを除外できます。

MCP サーバーはターミナルの権限で実行され、設定された拡張子と除外設定に一致するファイルのみを読み取ります。機密性の高いプロジェクトでは、サンドボックスまたはコンテナー内で実行してください。

---

設定

プロジェクト設定は .codegraphxrc（JSON）または codegraphx.config.json に記述します。

{
  "extensions": [".py", ".js", ".ts", ".jsx", ".tsx", ".html", ".css"],
  "ignore": [".git", "node_modules", "__pycache__", ".venv", "dist", "build", "coverage"],
  "outputDir": ".codegraphx",
  "outputFile": "codebase.json",
  "bloomErrorRate": 0.01
}

.codegraphx/ と .codegraphx.db を .gitignore に追加してください。これらはビルド成果物です。

---

FAQ

毎回スキャンを実行する必要がありますか？ いいえ。MCP サーバーは初回使用時に自動でインデックスを作成します。変更後に更新するには、再スキャンするか cgx watch を実行してください。再スキャンのたびに全体がクリーンな状態で書き換えられるため、削除や名前の変更によって古いグラフデータが残ることはありません。

大規模なコードベースにも対応していますか？ はい。増分解析により、変更されていないファイルはキャッシュから提供され、変更されたファイルのみが再解析されます。

非公開またはプロプライエタリなコードも使えますか？ 問題ありません。すべてローカルで実行され、マシンの外にデータが送信されることはありません。

MCP に「Disconnected」と表示されます。 絶対パスで node を指定し、cwd／--project-root を確認してください。プロジェクトのスコープでは gemini trust を実行し、標準エラー出力も確認してください（上記の手動セットアップを参照）。

ブルームフィルターの精度はどのくらいですか？ bloomErrorRate で調整できます（デフォルトは 0.01）。偽陽性が発生した場合はフォールバック検索が実行されますが、偽陰性は発生しません。

---

貢献

git clone https://github.com/techcraze00/CodeGraphX.git
cd codegraphx
npm install
npm link          # exposes `codegraphx` / `cgx` globally
npm test

言語を追加するには、Tree-sitter 文法を package.json に追加し、src/languages/<lang>/ にアダプターを作成し、src/languages/index.js に登録して、tests/golden/ にゴールデンフィクスチャを追加してください。

---

ライセンス

MIT © 2026 Prayas Jadhav。詳細は LICENSE を参照してください。

---

リンク

• ウェブサイト／ドキュメント： techcraze00.github.io/CodeGraphX
• パッケージ： npm の codegraphx
• リポジトリ： github.com/techcraze00/CodeGraphX
• 課題： github.com/techcraze00/CodeGraphX/issues

謝辞

Tree-sitter · Model Context Protocol · Kysely · TOON · bloom-filters

CodeGraphX — コードベースを瞬時に理解。

_{開発者にも AI エージェントにも役立つように作られています。}