CompareGraph

CompareGraph

Compare many code repositories feature by feature: which one has what, with the file and lines that show it.

Get started · Usage · Commands · MCP tools · FAQ · Troubleshooting · Reports

You keep clones of the projects you care about, your own and other people's, and you write down the features you want to compare. CompareGraph reads every clone into one graph and helps you, or your coding agent, fill in a table of features against repositories. Each answer is has, partial or none, and each points at the code, or at the search that found nothing. It is free and open source (Apache-2.0), one program on your machine; it reads clones and never runs them, and the engine never calls an AI model or the network.

What you will see in ten minutes: the same kind of table for a small sample, on your screen, after installing and six commands. On your own clones, add the build: 0.82 s for 85 files to 6.20 s for 797 files on our host (timing report).

---

Get started

One binary, no runtime. Linux x64 and arm64, macOS arm64 and x64, Windows x64; anywhere else, build from source.

1. Install the binary

The install script downloads one file, the comparegraph binary for your platform, checks it against the release's SHA256SUMS, and copies it to ~/.local/bin. It does not use sudo and changes nothing else. Read it first if you like:

# 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: written to %LOCALAPPDATA%\Programs\comparegraph and added to your user PATH; open a new terminal. COMPAREGRAPH_INSTALL_DIR moves the binary. The scripts check the checksum only. Releases from v0.1.2 also carry a build-provenance attestation, which the scripts do not check; check it yourself with gh attestation verify -R MassRelayAI/comparegraph (release notes).

No pipe to a shell: Homebrew, npm, by hand, from source

Homebrew, macOS and Linux: brew install massrelayai/tap/comparegraph.

npm, any of the five platforms with Node 18 or newer (the package wraps the same release binaries): npx -y @MassRelayAI/comparegraph --version, or npm i -g @MassRelayAI/comparegraph.

By hand: comparegraph- and SHA256SUMS from the latest release; check with sha256sum -c --ignore-missing SHA256SUMS. From source, anywhere Rust 1.85 or newer runs: cargo install --locked --git https://github.com/MassRelayAI/comparegraph comparegraph (--locked matters: the Perl grammar's newest release on crates.io is yanked, and only Cargo.lock resolves).

2. See it work on the sample

The sample repository and the example list of features live in this repository, not in the binary, so the first command downloads a copy of it. Run these in any folder; they make two folders side by side, comparegraph and 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

The table shows has for symbols.extraction and - (not yet answered) for the other nine features. The commands take under a second in all. Usage shows the real output of every step.

3. Compare your own repositories

The example pack describes code-graph tools. For your own field you write the list of features yourself, as a small rows.md; three rows are enough to start.

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 drafts a list of shared words (name, file, extract, ...), not features; keep the ones that matter, define them, and save the file as families/libs/rows.md:

---

family: libs description: the three features I want to compare

---

Then comparegraph family add families/libs, map, claim and matrix libs as in step 2. map gives places to read, not verdicts: you, or your agent, open them and write each claim. The column rules are in Usage.

4. Wire up your agents (optional)

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

Registers the MCP server with every agent it finds on the machine (twelve: Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Hermes, Windsurf, Antigravity, Kiro, Copilot, Copilot CLI, Qwen Code), writes a short rules block into the workspace's instruction file, and for Claude Code a session-start hook. It only wires agents; it indexes nothing. Already installed? comparegraph doctor tells you what is wired.

Claude Code as a plugin, or your agent's own command

Claude Code as a plugin: the seven skills, the server and the hook in one install (Claude Code 2.1.275 or newer; claude plugin install … does the same from a shell):

/plugin install comparegraph --marketplace MassRelayAI/comparegraph

With the plugin enabled, setup --apply leaves Claude Code's server and hook to the plugin (their rows read plugin) and still writes the rules block.

Your agent's own command, run in the workspace; each writes the user-scope entry setup would (Claude Code's default scope, local, is one doctor does not read), so doctor reads it as aligned:

The server is listed in the MCP Registry as io.github.MassRelayAI/comparegraph; the table has every client's file.

To uninstall, see Agents, platforms, uninstall. Free and open source, with no paid tier; questions and bugs go to GitHub issues, security reports to SECURITY.md.

---

Why CompareGraph

Measured on six study copies and 30 features, binary 0.1.1: numbers in docs/assets/cost.json, method and caveats in the answer-size report.

You have many repositories and one question: who has what? Reading each by hand does not scale, a summary without a line number cannot be checked, and notes go stale when the code moves. Five properties, each one you can test:

1. Deterministic. The same clone and version give the same store_hash. comparegraph check rebuilds and compares, and an incremental build must equal build --full (equal on both large trees in the Plan 6 report).
2. An evidence class on every answer. Each envelope says observed, derived, inferred or unknown, plus a limitations[] list of what the engine cannot see.
3. A claim needs a citation that resolves now. has and partial need --at path:start-end matching a stored node; otherwise the engine refuses. A moved citation shows as unknown* after check.
4. `none` needs proof of absence. Either --searched terms that find nothing, the same terms with every hit named in --read-hits as opened and rejected, or the graph check: four channels (symbols, paths, community terms, node kinds) all empty. A none with --searched must name as read the top 10 ranked candidates that absent-check --searched returns (read_set); candidates beyond the cap are recorded as a read_capped limitation. An unread candidate in the top 10 refuses the claim and names it.
5. No model in the engine. Scores, bands, descriptions and candidates are computed from stored facts. An agent may do the reading; the engine only stores, checks and refuses.

Agains