CompareGraph

CompareGraph

Already installed? Run comparegraph doctor.

Compare many repositories with Claude Code, Codex, Cursor, Gemini CLI, Windsurf, OpenCode and six more agents

One graph over many clones · a verdict with a citation on every cell · 29 languages · 100% local, no model calls
One Rust binary

Usage · Commands · MCP tools · FAQ · Troubleshooting · Roadmap · Reports

CompareGraph parses many cloned repositories into one SQLite graph. It scores each clone against a taxonomy (a "family" of features) and records, per clone and feature, a verdict with a citation to a file and line range. It is one Rust binary with a CLI and an MCP server. It reads clones and never runs them. It never calls a model.

Get started

No runtime to install: one binary. Node users can run the same binary through npx -y @massrelay-ai/comparegraph.

1. Install the binary

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/massrelay-ai/comparegraph/main/scripts/install.sh | sh

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

_{Checked against the release's SHA256SUMS (linux-x64, linux-arm64, darwin-arm64, darwin-x64, win32-x64; from v0.1.2 also attested: gh attestation verify <asset> -R massrelay-ai/comparegraph), then written to ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\comparegraph, added to your user PATH; open a new terminal there). COMPAREGRAPH_VERSION=v0.1.1 pins a release; COMPAREGRAPH_INSTALL_DIR moves the binary.}

2. Wire up your agents

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.}

/plugin install comparegraph --marketplace massrelay-ai/comparegraph

3. Add and build clones

comparegraph add ../some-clone --name some
comparegraph build some

_{A clone is read, never run. One store per workspace, under .comparegraph/. Rebuilds are incremental and hash-equal to build --full.}

4. Compare

comparegraph family add families/example-code-graph-tools   # the taxonomy
comparegraph map some example-code-graph-tools              # ranked candidates per feature, writes nothing
comparegraph claim some symbols.extraction has --author me --at <path>:<start>-<end>
comparegraph matrix example-code-graph-tools                # features x clones, prevalence, gaps

_{The family pack ships in this repository, not in the binary, so run these inside a clone of it. The sample below walks the shipped sample through all of these with real output.}

Quick start on the shipped sample

The example pack and sample repositories ship in the repository, not in the binary. Usage walks fixtures/typescript against the ten-feature example pack, from add to export vault, with the real output of every step.

To uninstall, see Agents, platforms, uninstall.

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.

For: teams comparing their product with the field, due diligence on a set of projects, a newcomer mapping a field (family propose drafts the taxonomy), and coding agents that need compact facts over MCP.

How it works

The three rules

1. The engine never calls a model. Every score, band, description and candidate is computed from stored facts.
2. A claim needs a citation that resolves now. has and partial need --at path:start-end matching a stored node. none needs --searched terms that find nothing, or the graph check. Otherwise the engine refuses or writes unknown.
3. Claims and decisions are append-only, enforced by the database. A change is a new row naming the one it supersedes. The latest wins, and the trail stays.

A candidate from search or map is labelled candidate, never has. Design: docs/design.md.

The flow and the code rings as diagrams: docs/design.md.

A family in the graph

A family is a taxonomy: groups of features, each with a definition and a test for what counts as having it. A cell is one clone against one feature, holding a verdict (has, partial, none) and, for has and partial, a citation. The picture draws the family code-graph-tools with the agreed cells of the mapping gold; comparegraph export vault shows the same graph live in Obsidian.

Plugins and the second engine

An external provider is any executable that speaks JSON lines on stdin and stdout: the host writes one request line, closes stdin, and reads answer lines until the first ok answer. Everything it prints is data, parsed into our own types. Register one in comparegraph.toml ([providers.mine] command = "tools/my-provider") or as comparegraph-provider-<name> on PATH, with a comparegraph-plugin.toml manifest beside it (kind, name, protocol = "1", languages, network). Without a manifest it runs only with --allow-unverified.

Full protocol, guards, a 25-line Python provider and the code-review-graph adapter (a second engine behind build --providers reference,crg): docs/dev/plugin-protocol.md.

Families and the seven skills

A family is a directory with a rows.md; two packs ship, families/example-code-graph-tools (10 features, the quick start) and families/code-graph-tools (30 features, the mapping gold). The column rules, synonyms and family propose are in Usage.

The method is seven plain-markdown skills in skills/ that any agent can read. Each gives when to use the verb, the exact commands, what the engine refuses, and how to check. In Claude Code the skills and the MCP server arrive together as one plugin (Get started); other agents read the skills/ directory from the clone.

Using it

Four pages under docs/ hold the reference; each is a few clicks from here.

What you get

Four levels, each answering how it knows: the repo surface, module communities, symbols (callers, callees, blast radius, tests, entry points, dead-code candidates) and claims (verdict, citation, author, trail). Every answer is one JSON envelope with an evidence class. Usage has the table and a real show answer.

CLI reference

Global options --root and --pretty, then verbs in four groups: build and inspect, graph queries, families and claims, exports and agents. Commands lists every verb with the flags that matter.

MCP tools

comparegraph mcp serves eighteen tools over stdio (seventeen read-only, one write: comparegraph_claim); there is deliberately no decide tool. MCP tools has the table; docs/catalog.json is the machine-readable source and catalog --check guards it in CI.

The vault, configuration, library

comparegraph export vault --out ./vault writes an Obsidian-style markdown vault of notes with generated descriptions. Settings are --root and COMPAREGRAPH_* environment variables, and the crate exposes each verb as a function. All three are in Usage.

How good is it

Every number below is copied from a report in this repository; read its caveats before quoting one. All were measured on 2026-10-13 on one shared host.

On the hand-labelled gold of call sites, CompareGraph reaches precision 0.995 and recall 0.834 pooled, against 0.956 / 0.736 for code-review-graph through its adapter and 0.708 / 0.506 for codegraph. It builds a 38,258-file repository in 499.6 s, and impact on a 1.29M-edge graph answers in 2.5 s; the tables below carry the caveats. Data: accuracy.json, scale.json; parity report: engine parity.

Languages

29 languages are parsed. Five are resolved deeply. Four have a measured gold standard. Read the tiers, not the headline. Every grammar (32 ids: tsx, jsx and mjs count apart) has a fixture with a committed graph digest in fixtures/languages/, so a grammar bump that changes any graph fails CI and is re-golded on purpose.

Agents, platforms, uninstall

comparegraph setup writes the entry; comparegraph doctor reports each client's state (aligned, stale, conflict, missing, unverified, plugin). --client all acts only on clients that look installed. plugin: left to the Claude Code plugin when comparegraph@comparegraph is enabled and --client all is used; name --client claude to write anyway. A bare comparegraph command that resolves on PATH to the registered binary counts as aligned. setup --apply is additive and leaves a backup named <file>.bak-<unix-seconds>; a differing entry is left alone unless you pass --force.

setup also writes a rules block into the agent's instruction file and, for Claude Code, a SessionStart hook; Usage has the details.

Platforms: every release builds linux-x64, linux-arm64, darwin-arm64, darwin-x64 and win32-x64 on their own runners and ships each as a release asset listed in SHA256SUMS; the Homebrew tap follows the release. The test suite runs on linux-x64 only. Anywhere Rust 1.85+ runs, build from source. Local only: the engine makes no network call, the MCP server speaks over stdio, the store is one SQLite file you own.

Uninstall: remove the entry above (in Claude Code with the plugin, /plugin uninstall comparegraph), then delete the binary (~/.local/bin/comparegraph, brew uninstall comparegraph or cargo uninstall comparegraph), and rm -r .comparegraph in each workspace.

FAQ and troubleshooting

• FAQ: how it differs from code-review-graph and codegraph (and what they have that it does not), whether it uses a model (no), whether it adopts code for you (no), why some call edges are 0.5, and what it does not do.
• Troubleshooting: twelve symptoms with their causes, from no workspace and a refused none claim to a silent session-start hook.
• Start with comparegraph doctor: it reports the store, every provider and each client's registration.

Roadmap

Nothing below exists yet, and the maintainer decides the order. Full list with the measurement behind each item: docs/roadmap.md.

• Next measured lever: a text channel in the store (doc-comment and signature tokens) and per-family synonyms, for map on unseen clones.
• Port-kit export for an adopted feature; feature stats export; claim import and family import/export.
• Graph-parity queries, a C/C++/C# resolver, a per-file analysis cache, more clients (Zed, Continue).

Documentation

Contributing, licence, third-party code

Security reports go to [email protected] or a private advisory (SECURITY.md); conduct reports to the same address (CODE_OF_CONDUCT.md).

Read CONTRIBUTING.md and AGENTS.md first. A bug fix starts with a failing test, extraction changes extend a conformance fixture, and no model or network call enters the engine. CI runs clippy, the suites, the conformance and language digests, and cargo-deny (licences, advisories, sources; deny.toml). The vendored parser layer comes from graphmind (MIT); see docs/THIRD_PARTY_NOTICES.md. Licence: Apache-2.0, see LICENSE.