CGIS Code Graph

🧠 CGIS：コードグラフ・インテリジェンス・システム

推測する代わりに、AI エージェントがクエリできるコードグラフ

「これを変更したら何が壊れますか？」と尋ねれば、推測ではなく呼び出しチェーンが得られます。

CGIS は tree-sitter でリポジトリを解析し、完全修飾シンボルと、それらの間の呼び出し、インポート、包含関係からなるグラフを構築して SQLite に保存し、MCP 経由で AI エージェントに提供します。本来なら grep してファイル全体を読むエージェントも、代わりにグラフに問い合わせます。

• 言語： Python · TypeScript / TSX · Go（構造とメトリクスのみ。影響分析の回答は、読み取って確認するための手がかりです — exp4。1 つのライブラリ golang/crypto、その大部分を占める ssh パッケージで測定。アプリケーションでは未測定） · JSON と YAML（データキーの宣言のみ。--data-keys でデータキーを有効にした場合。シンボル、呼び出し、影響分析は対象外）
• 実行環境： ローカル — アカウント不要、テレメトリーなし。グラフがディスクから外に出ることはありません（唯一のオプトインによる例外）

$ cgis ingest src --output graph.db
$ cgis impact cgis.query.engine.QueryEngine.get_flow_graph --db graph.db --depth 2
🔍 Analyzing transitive upstream callers of: cgis.query.engine.QueryEngine.get_flow_graph

METHOD cgis.query.engine.QueryEngine.get_flow_graph (cgis/query/engine.py:215)
├── FUNCTION cgis.query.context.context_service._collect_callees (cgis/query/context/context_service.py:44)
│   └── FUNCTION cgis.query.context.context_service.build_context (cgis/query/context/context_service.py:96)
└── METHOD cgis.guardian.collector.ContextCollector._graph_sections (cgis/guardian/collector.py:174)
    ├── METHOD cgis.guardian.collector.ContextCollector.collect_graph_context (cgis/guardian/collector.py:213)
    └── METHOD cgis.guardian.collector.ContextCollector.collect_for_chunk (cgis/guardian/collector.py:303)

実際の出力 — CGIS 自身のソースに対して実行した結果です。

---

🚀 クイックスタート

Claude Code で使う（最速）

/plugin marketplace add zaebee/codegraph-brain
/plugin install cgis@codegraph-brain

これにより、MCP サーバーと、ファイルを読む代わりにいつグラフをクエリするかをエージェントに教えるスキル、そして初回使用時にグラフを構築する /cgis:ingest が導入されます。サーバーは必要に応じて uvx 経由で PyPI から取得されるため、クローンやビルドは不要です。

その他の MCP クライアント（Cursor、Claude Desktop など）

{
  "mcpServers": {
    "cgis": { "command": "uvx", "args": ["--from", "codegraph-brain", "cgis-mcp"] }
  }
}

ターミナルから

# No install needed — uvx fetches it from PyPI
uvx --from codegraph-brain cgis ingest ./my-project --output graph.db

uvx --from codegraph-brain cgis impact "my_module.core_function" --db graph.db --depth 5   # who calls this
uvx --from codegraph-brain cgis trace  "my_module.MyClass.run"   --db graph.db --depth 3   # what this calls
# add --format mermaid (or json) to either for a diagram or machine-readable output

または、常時使えるようにインストールします：pip install codegraph-brain（Python 3.12 以降）を実行すると、cgis を直接使えます。コマンド一覧は CLI_USAGE.md をご覧ください。

---

📈 実運用規模での実証

CGIS は、4 つの言語、8,146 件のコミットを含み、毎日リリースされている、実稼働中の 12 リポジトリからなる環境で動作しています。FastAPI バックエンドでは、87,845 件のエッジの 82.7% を確定的に分類し、残りの 17.3% については、ターゲットを捏造するのではなく、そのまま表示します。その中には CGIS 自身の未解決部分も含まれます。

この割合は #459 の 11.4% から上昇しました。#459 では、存在しないシンボルへの呼び出しを解決済みとして数えるのをやめました。残りの約 4 ポイントは、発見不可能なものではなく、既知のリゾルバーの未解決部分です。app/ を取り込むと、インポートに含まれる app. プレフィックスが取り除かれますが、インポートパス側ではまだ両者を照合できていません。同じバックエンドをパッケージのルートから取り込むと、13.2% と報告されます。この数値は、現時点でツールが配置できないと認めている割合であり、不都合な方向に動くこともあります。

事例紹介を読む → — CGIS が対象としていないものを含め、すべての数値は測定済みで、再現可能です。

---

🤔 グラフを使う理由と、その違い

テキスト検索では、関連がありそうなチャンクがエージェントに渡されます。しかし、save という名前の3つの関数のどれに呼び出しが到達するのか、あるいは呼び出し元を5つさかのぼった先に何があるのかは判断できません。CGIS は、ソースから判定できる場合、すべての呼び出し箇所を完全修飾名に解決します。解決できない場合は、エッジを未解決として記録して件数を集計し、もっともらしい推測で補うことはありません。

使用しているもの	CGIS が追加する機能
エージェントでの grep ／ファイル読み込み	ファイル全体にコンテキストを費やすことなく、1回の呼び出しで推移的な呼び出し元と呼び出し先を取得できます
LSP ベースのシンボルツール（例：Serena）	マルチホップの影響分析、結合度、PageRank、ドリフト分析に使える、リポジトリ全体の永続化されたグラフ
リポジトリマップ（例：aider）	たどって監査できる解決済みエッジと、報告される解決済み／未解決の比率

---

🤖 MCP ツール

主なツール：

ツール	わかること
cgis_ingest	グラフの構築または増分更新
cgis_overview	どこから始めるか：FQN がまだわからない場合の規模と最大のパッケージ
cgis_find_symbol	部分一致する名前 → 候補となる FQN
cgis_analyze_impact	これを変更すると、上流のどこが壊れるか？
cgis_trace_flow	推移的に何を呼び出すか？
cgis_get_structure	クラス／モジュールの階層
cgis_context	1つのシンボル用の簡潔な GraphRAG コンテキストパッケージ
cgis_metrics	結合度、ゴッドクラス、PageRank、パッケージの凝集度
cgis_audit_reachability	認可／IDOR のカバレッジ — すべてのハンドラーからガードに到達できるか？
cgis_drift	各ドメインが宣言されたパターンからどれだけ逸脱しているか
cgis_validate	グラフの整合性：解決済みエッジと未解決エッジ

全16ツールとパラメーター：MCP_REFERENCE.md。

---

🏗️ 仕組み

1. 抽出 — tree-sitter パーサーが各ファイルをノードと生の呼び出しエッジに変換します。
2. 解決 — ResolverEngine が生の呼び出しを完全修飾名に対応付けるか、明示的に未解決のままにします。
3. 保存 — SQLite にグラフを保持し、グラフを対象に幅優先探索でクエリを実行します。

graph LR
    A[Source Code] --> B[Extractors]
    B --> C[Resolver Engine]
    C --> D[(SQLite Graph DB)]
    D --> E[MCP Server]
    D --> F[Prompt Compiler]
    E --> G[AI Agents]
    F --> G

詳細と、変更のたびに CGIS が独自のソースから再生成するパイプライングラフについては、HOW_IT_WORKS.mdをご覧ください。

---

🛡️ Guardian：グラフを活用したコードレビュー

Guardian は CGIS に組み込まれた LLM レビュアーです。差分テキストだけでなく、コンテキストとして グラフ を使ってプルリクエストをレビューします。CI で実行され、該当する行にインラインコメントを投稿します。

• 2 段階の、再現率を重視したレビュー： ファインダーが考えられるすべての不具合を洗い出し（再現率を最適化）、その後、別の懐疑者パスで誤検出を除外します。人間のレビュアーの作業に近く、適合率を条件にした単一のプロンプトよりもはるかに信頼性があります。
• ローカル または クラウド、ベンダーロックインなし： 無料のローカル推論には Ollama（qwen2.5-coder、llama3.1、granite-code など）を、クラウドには Mistral / Gemini / Claude を指定できます。組み合わせて使うこともできます。高性能なクラウドのファインダーと、無料のローカルな クロスモデル 懐疑者を組み合わせられます。
• グラフを活用したコンテキスト： レビュアーは影響グラフ、アーキテクチャの乖離、プロジェクトのオントロジーを参照するため、単純な差分レビューでは見つけられない構造上の不具合や規約違反を検出できます。
• 決定論的な位置指定： すべてのインラインコメントは、モデルが推測した（誤っていることの多い）行ではなく、差分からの逐語的な引用によって位置が決まります。
• 自ら使い、評価： Guardian は CGIS 自身のプルリクエストをレビューし、ベンチマークハーネスで厳選された正解データと照合してスコアを算出します。そのため、プロンプトの変更は推測ではなく検証に基づきます。

# Build the graph, then review a PR with a local model (no API key)
cgis ingest ./src --output graph.db
GUARDIAN_PROVIDER=ollama GUARDIAN_MODEL=qwen2.5-coder:14b \
  uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline

# Or a Claude skeptic over a Mistral finder: Claude Haiku 5.5 unless GUARDIAN_SKEPTIC_MODEL names
# another, at GUARDIAN_ANTHROPIC_EFFORT=low unless set (low|medium|high|xhigh|max). Claude models
# reject a sampling temperature, so GUARDIAN_TEMPERATURE must be unset.
GUARDIAN_SKEPTIC=anthropic ANTHROPIC_API_KEY=... MISTRAL_API_KEY=... \
  uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline

GPU が手元にありませんか？ ノートブックの GPU でベンチマークを実行 → — 判定用の LLM がなくてもフィクスチャのスコアを算出できるため、最初から最後まで無料です。または、Guardian をリモートの Ollama に接続 → — frp stcp トンネルを経由し、パブリックポートを開放せずに接続できます。プロンプトが気づかれないまま切り詰められたレビューを拒否するガードも備えています。

---

🔒 プライバシー

CGIS は何も収集しません。テレメトリも、分析データも、アカウントもありません。コードと、そこから構築されたグラフはお使いのマシン上に保持されます。例外はオプトインの場合のみです。Guardian をクラウドモデルで実行すると、レビュー対象の差分が選択したプロバイダーに送信されます。詳しくは PRIVACY.md をご覧ください。

---

🛠️ 開発

Python 3.12+ と uv が必要です。

git clone https://github.com/zaebee/codegraph-brain && cd codegraph-brain
uv sync
make pytest

規約については CONTRIBUTING.md をご覧ください。厳格な MyPy、リンティング、オントロジーへの準拠が含まれます。

---

💼 アーキテクチャ監査

CGIS は無料で、自分で実行できます。ツールではなく分析結果をご希望の場合は、コードベースの構造を固定料金で監査します。認可の適用範囲、影響範囲、結合度、アーキテクチャの乖離を分析し、5 営業日で納品します。料金は一律 2,400 ドルで、分析では確認できない項目も明示します。監査内容を見る →