CompareGraph

CompareGraph

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

[CI] [Release] [License: Apache-2.0, free]

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.

[A table of four features against four repositories, code-review-graph, srclight, codanna and CodeGraph. All four have full-text search and embedding search; module communities are in code-review-graph and srclight, partly in CodeGraph and not in codanna; diff-aware review is in all but codanna. One has cell cites code_review_graph/communities.py::detect_communities, and one none cell records the search that found nothing. The cells are the agreed verdicts of the mapping gold in fixtures/gold-map.]

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 itcurl -fsSLO https://raw.githubusercontent.com/MassRelayAI/comparegraph/v0.1.3/scripts/install.shless install.shCOMPAREGRAPH_VERSION=v0.1.3 sh install.sh
# the same in one line, script from main, latest releasecurl -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 <asset> -R MassRelayAI/comparegraph (release notes).}

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 heremkdir cg-try && cd cg-try                                           # your workspacecomparegraph add ../comparegraph/fixtures/typescript --name tsfix   # read, never runcomparegraph build tsfix                                            # parse itcomparegraph family add ../comparegraph/families/example-code-graph-toolscomparegraph map tsfix example-code-graph-tools                     # places to readcomparegraph claim tsfix symbols.extraction has --author me --at src/util.ts:11-11comparegraph 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 diskcomparegraph add ../their-lib --name theirscomparegraph build mine && comparegraph build theirscomparegraph 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: libsdescription: 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 |

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

/plugin install comparegraph --marketplace MassRelayAI/comparegraph

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

[Six projects hold 106.1 MB of source (about 26.5 M tokens, an estimate); the ranked candidates for 30 features on all six are 336 KB (about 84 k tokens) and the matrix is 6 KB; candidates are places to read, not verdicts.]

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

[Workflow: clone repos, one graph, taxonomy, verdicts with citations, decisions, matrix]

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 in the graph: 30 features in 10 groups, six clones, 121 cells with a verdict both readers agreed on (93 has, 9 partial, 19 none), drawn as edges from feature to clone coloured by verdict]

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. The manifest is a declaration, not a signature: no hash of the executable is checked, and a provider runs as its own program with your permissions. Prefer a path in comparegraph.toml, which is looked up first, to a name found on PATH. A manifest's network value is passed to the provider as COMPAREGRAPH_NETWORK, not enforced.

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.

[Call edges, precision and recall per engine on a 750-site hand-labelled gold: CompareGraph 0.995 / 0.834 pooled, code-review-graph via adapter 0.956 / 0.736, codegraph 0.708 / 0.506.]

[Scale: files parsed against nodes, edges and build seconds on four trees, and query times on the 1.29M-edge openclaw graph.]

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 (how to check it yourself, and what is not yet enforced: FAQ), 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, whether it is free and who supports it, how to check that it sends nothing, what it does with a repository you do not trust, 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.