CompareGraph

CompareGraph

複数のコードリポジトリを機能ごとに比較し、どれに何があるかを、それを示すファイルと行番号とともに確認できます。

始める · 使い方 · コマンド · MCP ツール · よくある質問 · トラブルシューティング · レポート

自分のプロジェクトや他の人のプロジェクトなど、関心のあるプロジェクトのクローンを手元に置き、比較したい機能を書き出します。CompareGraph はすべてのクローンを読み込んでひとつのグラフにまとめ、あなたやコーディングエージェントが、リポジトリごとの機能を一覧表に記入するのを支援します。各項目の回答は has、partial、none のいずれかで、コードまたは何も見つからなかった検索結果を示します。無料のオープンソース（Apache-2.0）ソフトウェアで、マシン上で動作する単一のプログラムです。クローンを読み込むだけで、実行することはありません。また、エンジンが AI モデルやネットワークを呼び出すこともありません。

10分で確認できること： インストール後、6つのコマンドを実行すると、小規模なサンプルについて同じ種類の表が画面に表示されます。自分のクローンで試す場合は、ビルドを追加してください。私たちのホストでは、85ファイルで0.82秒、797ファイルで6.20秒でした（計測レポート）。

始める

ランタイム不要の単一バイナリです。Linux x64およびarm64、macOS arm64およびx64、Windows x64に対応しています。それ以外の環境では、ソースからビルドしてください。

1. バイナリをインストールする

インストールスクリプトは、プラットフォーム用の comparegraph バイナリを1つダウンロードし、リリースの SHA256SUMS と照合して、~/.local/bin にコピーします。sudo は使用せず、それ以外の変更も行いません。必要であれば、先に内容を確認してください。

# macOS / Linux: fetch the script from the v0.1.3 tag, read it, then run it
curl -fsSLO https://raw.githubusercontent.com/MassRelayAI/comparegraph/v0.1.3/scripts/install.sh
less install.sh
COMPAREGRAPH_VERSION=v0.1.3 sh install.sh

# the same in one line, script from main, latest release
curl -fsSL https://raw.githubusercontent.com/MassRelayAI/comparegraph/main/scripts/install.sh | sh

# Windows x64 (PowerShell)
irm https://raw.githubusercontent.com/MassRelayAI/comparegraph/main/scripts/install.ps1 | iex

_{Windows：%LOCALAPPDATA%\Programs\comparegraph に書き込み、ユーザーの PATH に追加します。新しいターミナルを開いてください。COMPAREGRAPH_INSTALL_DIR でバイナリの保存先を変更できます。スクリプトが確認するのはチェックサムのみです。v0.1.2 以降のリリースにはビルド来歴のアテステーションも付属していますが、スクリプトでは確認しません。gh attestation verify <asset> -R MassRelayAI/comparegraph を使って、ご自身で確認してください（リリースノート）。}

2. サンプルで動作を確認する

サンプルリポジトリと機能の例一覧はバイナリではなくこのリポジトリに含まれているため、最初のコマンドでそのコピーをダウンロードします。任意のフォルダーで次のコマンドを実行してください。隣り合う2つのフォルダー comparegraph と cg-try が作成されます。

git clone --depth 1 https://github.com/MassRelayAI/comparegraph   # the sample lives here
mkdir cg-try && cd cg-try                                           # your workspace
comparegraph add ../comparegraph/fixtures/typescript --name tsfix   # read, never run
comparegraph build tsfix                                            # parse it
comparegraph family add ../comparegraph/families/example-code-graph-tools
comparegraph map tsfix example-code-graph-tools                     # places to read
comparegraph claim tsfix symbols.extraction has --author me --at src/util.ts:11-11
comparegraph matrix example-code-graph-tools                        # the table

表では、symbols.extraction に has が、残り9つの機能には -（未回答）が表示されます。どのコマンドも1秒以内に完了します。使い方では、各手順の実際の出力を確認できます。

3. 独自のリポジトリを比較する

サンプルパックにはコードグラフのツールが記述されています。独自の分野で使う場合は、小さな rows.md を作成して、機能一覧を自分で記述します。まずは3行あれば十分です。

comparegraph add ../your-lib --name mine --as-root   # any clones on your disk
comparegraph add ../their-lib --name theirs
comparegraph build mine && comparegraph build theirs
comparegraph family propose libs --repos mine,theirs # optional draft

family propose は機能ではなく、共有語の一覧（name、file、extract、...）を下書きします。重要な語を選び、それぞれを定義して、ファイルを families/libs/rows.md として保存してください。

---
family: libs
description: the three features I want to compare
---
| id | group | feature | definition | counts_as_has | tier | weight |
|---|---|---|---|---|---|---|
| search.fulltext | search | Full-text search | Search over names or text through an index | a query entry point over a full-text index | basics | 2 |
| search.embeddings | search | Embedding search | Search by vector similarity | code that embeds text and ranks by similarity | extra | 1 |
| graph.communities | graph | Module communities | Groups of related code found from the graph | a clustering pass over the graph | extra | 1 |

その後、手順2と同様に comparegraph family add families/libs、map、claim、matrix libs を実行します。map が示すのは確認すべき箇所であり、結論ではありません。ご自身またはエージェントがそれらを開き、各主張を記述します。列のルールについては使い方を参照してください。

4. エージェントを接続する（任意）

comparegraph setup --apply      # omit --apply for the plan; --scope project for an entry you commit
comparegraph doctor             # each client's state: aligned, stale, conflict, missing, plugin

_{マシン上で見つかったすべてのエージェント（12 種類：Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Hermes、Windsurf、Antigravity、Kiro、Copilot、Copilot CLI、Qwen Code）に MCP サーバーを登録し、ワークスペースの指示ファイルに短いルールブロックを書き込みます。また、Claude Code にはセッション開始フックを設定します。エージェントを接続するだけで、インデックス作成は行いません。すでにインストール済みですか？ comparegraph doctor で接続状況を確認できます。}

/plugin install comparegraph --marketplace MassRelayAI/comparegraph

アンインストールについては、エージェント、プラットフォーム、アンインストールを参照してください。無料のオープンソースで、有料プランはありません。質問やバグの報告は GitHub issues へ、セキュリティ上の報告は SECURITY.md をご覧ください。

CompareGraph を選ぶ理由

6 つの調査用コピーと 30 個の機能を対象に、バイナリ 0.1.1 で測定しました。数値は docs/assets/cost.json、手法と注意事項は回答サイズのレポートをご覧ください。

リポジトリがたくさんあり、知りたいことは 1 つです。それぞれに何があるのか。各リポジトリを手作業で読む方法では規模に対応できず、行番号のない要約は検証できません。また、コードが移動するとメモは古くなります。検証可能な 5 つの特性を備えています。

1. 決定論的です。 同じクローンとバージョンであれば、同じ store_hash が得られます。comparegraph check は再構築して比較し、増分ビルドは build --full と一致する必要があります（Plan 6 レポートにある 2 つの大規模ツリーでは一致しています）。
2. すべての回答に証拠クラスが付与されます。 各エンベロープには observed、derived、inferred、unknown のいずれかと、エンジンが確認できない内容を示す limitations[] リストが含まれます。
3. 主張には、現在も有効な引用が必要です。 has と partial には、保存済みノードと一致する --at path:start-end が必要です。一致しない場合、エンジンは拒否します。引用先が移動すると、check の後に unknown* と表示されます。
4. none には、存在しないことの証明が必要です。 何も見つからない検索語を指定する --searched、または同じ検索語で、見つかったすべての項目を開いて却下したものとして --read-hits に指定する方法が使えます。あるいはグラフチェックを使います。グラフチェックでは、4 つのチャネル（シンボル、パス、コミュニティ用語、ノード種別）がすべて空である必要があります。--searched を指定した none では、absent-check --searched が返す上位 10 件のランク付き候補を、確認済みとして指定する必要があります（read_set）。上限を超えた候補は read_capped の制限として記録されます。上位 10 件に未確認の候補がある場合、主張は拒否され、その候補が示されます。
5. エンジンにモデルはありません。 スコア、バンド、説明、候補はすべて保存済みの事実から算出されます。エージェントが内容を読むことはできますが、エンジンが行うのは保存、検証、拒否のみです。

対象：自社製品を業界と比較するチーム、プロジェクト群のデューデリジェンス、新たに分野の全体像を把握する人（family propose で分類体系の草案を作成）、MCP を通じて簡潔な事実を必要とするコーディングエージェント。

仕組み

3 つのルール

1. エンジンはモデルを呼び出しません。 スコア、バンド、説明、候補はすべて保存済みの事実から算出されます。
2. 主張には、現在も有効な引用が必要です。 has と partial には、保存済みノードと一致する --at path:start-end が必要です。none には、何も見つからない検索語を指定する --searched、またはグラフチェックが必要です。それ以外の場合、エンジンは拒否するか、unknown を書き込みます。
3. 主張と判断は、データベースによって強制される追記専用です。 変更は、置き換える対象を指定する新しい行として追加されます。最新のものが有効になり、履歴は保持されます。

search または map の候補には candidate のラベルが付き、has になることはありません。設計については、docs/design.mdをご覧ください。

フローとコードリングの図については、docs/design.mdをご覧ください。

グラフ内のファミリー

ファミリーとは分類体系です。機能のグループで構成され、それぞれに定義と、その機能を備えていると見なす基準となるテストがあります。セルは、1 つのクローンと 1 つの機能の組み合わせで、判定（has、partial、none）を保持します。has と partial の場合は引用も保持します。この図は、マッピングのゴールドデータに含まれる合意済みセルを用いて、ファミリー code-graph-tools を描画しています。comparegraph export vault を実行すると、Obsidian で同じグラフをリアルタイムに表示できます。

プラグインと 2 つ目のエンジン

外部プロバイダーとは、標準入力と標準出力で JSON Lines を扱う実行可能プログラムです。ホストはリクエストを 1 行書き込み、標準入力を閉じて、最初の ok 応答まで回答行を読み取ります。プログラムが出力する内容はすべてデータとして扱われ、独自の型にパースされます。comparegraph.toml に [providers.mine] command = "tools/my-provider" として登録するか、PATH 上に comparegraph-provider-<name> として配置し、同じ場所に comparegraph-plugin.toml マニフェスト（kind、name、protocol = "1"、languages、network）を用意してください。マニフェストがない場合、--allow-unverified を指定したときに限り実行されます。マニフェストは宣言であり、署名ではありません。実行可能ファイルのハッシュは検証されず、プロバイダーはユーザーの権限で独立したプログラムとして実行されます。PATH 上で見つかった名前より先に検索される、comparegraph.toml 内のパスを指定することをおすすめします。マニフェストの network 値は COMPAREGRAPH_NETWORK としてプロバイダーに渡されますが、強制はされません。

プロトコルの全仕様、ガード、25 行の Python プロバイダー、code-review-graph アダプター（build --providers reference,crg で使う 2 つ目のエンジン）については、docs/dev/plugin-protocol.md をご覧ください。

ファミリーと 7 つのスキル

ファミリーは rows.md を含むディレクトリです。2 つのパックが同梱されています。クイックスタート用の families/example-code-graph-tools（機能 10 個）と、マッピングのゴールドデータである families/code-graph-tools（機能 30 個）です。列のルール、同義語、family propose については、使い方をご覧ください。

この手法は、skills/ にある 7 つのプレーン Markdown スキルで構成されており、どのエージェントでも参照できます。それぞれのスキルでは、その動詞を使う場面、正確なコマンド、エンジンが拒否する内容、確認方法を説明しています。Claude Code では、スキルと MCP サーバーが 1 つのプラグインとして一緒に提供されます（始める）。それ以外のエージェントでは、クローン内の skills/ ディレクトリを参照してください。

使い方

docs/ にある 4 つのページがリファレンスです。ここからそれぞれ数回クリックするだけでアクセスできます。

得られるもの

4 つのレベルがあり、それぞれが「どのように把握しているのか」に答えます。リポジトリの概要、モジュールのコミュニティ、シンボル（呼び出し元、呼び出し先、影響範囲、テスト、エントリーポイント、デッドコード候補）、そして主張（判定、引用、作成者、履歴）です。回答はすべて、エビデンスクラスを含む 1 つの JSON エンベロープです。使い方には表と実際の show の回答があります。

CLI リファレンス

グローバルオプションの --root と --pretty に続き、動詞は 4 つのグループに分かれています。ビルドと調査、グラフクエリ、ファミリーと主張、エクスポートとエージェントです。コマンドには、重要なフラグとともにすべての動詞が記載されています。

MCP ツール

comparegraph mcp は、stdio 経由で 18 個のツールを提供します（読み取り専用が 17 個、書き込みが 1 個：comparegraph_claim）。意図的に decide ツールは用意していません。MCP ツールには表があり、docs/catalog.json が機械可読な情報源です。catalog --check により、CI でその内容が検証されます。

Vault、設定、ライブラリ

comparegraph export vault --out ./vault は、生成された説明を含む Obsidian 形式の Markdown Vault を書き出します。設定には --root と COMPAREGRAPH_* 環境変数を使用し、クレートでは各動詞を関数として公開しています。この 3 つすべてについては使い方をご覧ください。

性能はどの程度ですか

以下の数値はすべて、このリポジトリ内のレポートから転載したものです。引用する前に、レポートの注意事項を確認してください。すべて、共有ホスト 1 台で 2026-10-13 に測定しました。

手作業でラベル付けした呼び出し箇所のゴールドデータにおいて、CompareGraph の精度はプール値で 0.995、再現率は 0.834 です。アダプター経由の code-review-graph は 0.956 / 0.736、codegraph は 0.708 / 0.506 です。CompareGraph は 38,258 ファイルのリポジトリを 499.6 秒でビルドし、129 万エッジのグラフに対する impact の回答時間は 2.5 秒です。注意事項については、以下の表をご覧ください。データ：accuracy.json、scale.json。パリティレポート：エンジンのパリティ。

29 言語を解析します。そのうち5言語は詳細に解決され、4言語には測定済みのゴールドスタンダードがあります。見出しだけでなく、各ティアを確認してください。 すべての文法（tsx、jsx、mjsを別々に数えて32 ID）には、コミット済みのグラフダイジェストを含むフィクスチャが fixtures/languages/にあります。そのため、文法の更新でグラフが少しでも変わるとCIが失敗し、意図的にゴールドデータを更新する必要があります。

エージェント、プラットフォーム、アンインストール

comparegraph setup はエントリーを書き込みます。comparegraph doctor は各クライアントの状態（aligned、stale、conflict、 missing、unverified、plugin）を報告します。--client all は、インストールされているように見えるクライアントのみを対象にします。plugin：comparegraph@comparegraph が有効で、--client all を使用した場合は Claude Code プラグインに任せます。強制的に書き込むには、--client claude を指定します。PATH 上で登録済みのバイナリに解決される単独の comparegraph コマンドは、整合しているものとして扱われます。setup --apply は追加のみを行い、<file>.bak-<unix-seconds> という名前のバックアップを残します。異なるエントリーは、--force を指定しない限り変更されません。

setup は、エージェントの指示ファイルにルールブロックを書き込み、Claude Code の場合は SessionStart フックも書き込みます。詳細は使い方をご覧ください。

プラットフォーム：各リリースでは、専用のランナーで linux-x64、linux-arm64、darwin-arm64、darwin-x64、win32-x64 向けにビルドし、それぞれを SHA256SUMS に記載されたリリースアセットとして配布します。Homebrew tap はリリースに追随します。テストスイートは linux-x64 のみで実行されます。Rust 1.85 以降が動作する環境であれば、ソースからビルドできます。ローカルのみで動作します。エンジンはネットワーク通信を行わず（自分で確認する方法と、まだ強制されていないことについてはFAQをご覧ください）、MCP サーバーは stdio 経由で通信し、ストアは所有者自身が管理する単一の SQLite ファイルです。

アンインストール：上記のエントリーを削除し（プラグインを使用している Claude Code では /plugin uninstall comparegraph）、次にバイナリを削除します（~/.local/bin/comparegraph、brew uninstall comparegraph、または cargo uninstall comparegraph）。さらに、各ワークスペースで rm -r .comparegraph を実行します。

FAQ とトラブルシューティング

• FAQ：code-review-graph や codegraph との違い（および、それらにあって本ツールにはないもの）、モデルを使用するか（いいえ）、コードを自動で採用するか（いいえ）、一部の呼び出しエッジが 0.5 なのはなぜか、無料かどうかとサポート担当者、何も送信されないことを確認する方法、信頼できないリポジトリをどう扱うか、そして本ツールが行わないことについて説明します。
• トラブルシューティング：no workspace や拒否された none クレームから、セッション開始フックが無反応になる問題まで、原因とともに 12 の症状を説明します。
• まず comparegraph doctor を実行してください。ストア、すべてのプロバイダー、各クライアントの登録状況が報告されます。

ロードマップ

以下の項目はまだどれも実装されておらず、順序はメンテナーが決定します。各項目の根拠となる測定値を含む全リスト：docs/roadmap.md。

• 次に測定する改善策：ストアにテキストチャネル（ドキュメントコメントとシグネチャのトークン）を追加し、ファミリーごとの同義語を導入して、未確認のクローンでの map に対応します。
• 採用した機能の Port-kit エクスポート、機能統計のエクスポート、クレームのインポート、family import/export。
• グラフ同等性クエリ、C/C++/C# リゾルバー、ファイルごとの解析キャッシュ、対応クライアントの追加（Zed、Continue）。

ドキュメント

コントリビューション、ライセンス、サードパーティ製コード

セキュリティに関する報告は [email protected] または非公開のアドバイザリー（SECURITY.md）へ、行動規範に関する報告は同じアドレス（CODE_OF_CONDUCT.md）へお送りください。

まず CONTRIBUTING.md と AGENTS.md をお読みください。バグ修正では、失敗するテストから始めてください。抽出処理の変更では適合性フィクスチャを拡張してください。また、エンジンにモデルやネットワークへの呼び出しを追加しないでください。CI では clippy、各種テストスイート、適合性および言語のダイジェスト、cargo-deny（ライセンス、アドバイザリー、ソース；deny.toml）を実行します。ベンダー化されたパーサーレイヤーは graphmind（MIT）に由来します。詳しくは docs/THIRD_PARTY_NOTICES.md をご覧ください。ライセンスは Apache-2.0 です。詳しくは LICENSE をご覧ください。