Compare multiple code repositories feature by feature using a code graph and cited claims to generate a detailed comparison matrix.
Also known as MassRelayAI/comparegraph, @massrelayai/comparegraph
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.3
- Last commit
- Nov 12, 2026
- License
- Apache-2.0
What is CompareGraph MCP?
CompareGraph is an MCP server. Compare multiple code repositories feature by feature using a code graph and cited claims to generate a detailed comparison matrix.
Summary generated from the project's README
About CompareGraph MCP server
Comparing multiple code repositories feature by feature is what CompareGraph enables for developers and coding agents. By reading local clones of projects into a single code graph, it helps users generate a detailed comparison matrix that identifies which repository contains specific functionality. Each entry in the resulting table is categorized as has, partial, or none, and includes citations to the exact files and lines of code that support the claim.
This tool runs locally on your machine as a single binary and does not require an internet connection or an AI model to function. It reads your local code clones without executing them, ensuring privacy and security. Users can integrate it with various AI clients like Claude Code, Cursor, or Gemini CLI using the setup command. The engine focuses on storing, checking, and verifying claims rather than generating text, providing deterministic results with evidence classes like observed or derived for every answer.
What you can do with it
- 1Generate a feature comparison matrixCreate a table showing which repositories possess specific features with supporting code citations.
- 2Verify feature presence with citationsProvide exact file paths and line numbers to prove a repository has a specific capability.
- 3Automate repository analysis with AI agentsWire the server to coding agents to help them fill in feature tables automatically.
- 4Prove the absence of functionalityUse search terms and graph checks to confirm a feature is truly missing from a codebase.
Written from the project's README. Every use case is checked against a quote from it.
How to install CompareGraph MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall CompareGraph MCP in Claude Code
$ claude mcp add comparegraph -- npx -y @massrelayai/comparegraphInstall CompareGraph MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"comparegraph": {
"command": "npx",
"args": [
"-y",
"@massrelayai/comparegraph"
]
}
}
}Install CompareGraph MCP in VS Code
.vscode/mcp.json
{
"servers": {
"comparegraph": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@massrelayai/comparegraph"
]
}
}
}Install CompareGraph MCP in VS Code CLI
$ code --add-mcp '{"name":"comparegraph","type":"stdio","command":"npx","args":["-y","@massrelayai/comparegraph"]}'Install CompareGraph MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"comparegraph": {
"command": "npx",
"args": [
"-y",
"@massrelayai/comparegraph"
]
}
}
}Install CompareGraph MCP in Codex
$ codex mcp add comparegraph -- npx -y @massrelayai/comparegraphInstall CompareGraph MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.comparegraph] command = "npx" args = ["-y", "@massrelayai/comparegraph"]
Install CompareGraph MCP in Gemini CLI
$ gemini mcp add -s user comparegraph npx -- -y @massrelayai/comparegraphInstall CompareGraph MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"comparegraph": {
"command": "npx",
"args": [
"-y",
"@massrelayai/comparegraph"
]
}
}
}Configuration
COMPAREGRAPH_VERSION
| Name | Description | |
|---|---|---|
| COMPAREGRAPH_VERSION | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablemassrelayai/comparegraph is public and reachablegithub.com/massrelayai/comparegraph ↗Pass
- Package names this repository as its source@massrelayai/comparegraph names massrelayai/comparegraph as sourcenpmjs.com/package/@massrelayai/comparegraph ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @massrelayai/comparegraphnpmjs.com/package/@massrelayai/comparegraph/v/0.1.3#provenan ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/massrelayai/comparegraph ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @massrelayai/comparegraphPass
- No critical advisory in the package or its dependencies6 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubYou 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 also compares screens, not only code: the same page in two products, measured from its structure, with screenshots as context (below). 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 <asset> -R MassRelayAI/comparegraph (release notes).
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-<platform> 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
---
| 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 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: 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:
| Agent | Command |
|---|---|
| Claude Code | claude mcp add --scope user comparegraph -- comparegraph --root "$PWD" mcp |
| Codex | codex mcp add comparegraph -- comparegraph --root "$PWD" mcp |
| Gemini CLI | gemini mcp add -s user comparegraph comparegraph -- --root "$PWD" mcp |
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:
- Deterministic. The same clone and version give the same
store_hash.comparegraph checkrebuilds and compares, and an incremental build must equalbuild --full(equal on both large trees in the Plan 6 report). - An evidence class on every answer. Each envelope says
observed,derived,inferredorunknown, plus alimitations[]list of what the engine cannot see. - A claim needs a citation that resolves now.
hasandpartialneed--at path:start-endmatching a stored node; otherwise the engine refuses. A moved citation shows asunknown*aftercheck. noneneeds proof of absence. Either--searchedterms that find nothing, the same terms with every hit named in--read-hitsas opened and rejected, or the graph check: four channels (symbols, paths, community terms, node kinds) all empty. Anonewith--searchedmust name as read the top 10 ranked candidates thatabsent-check --searchedreturns (read_set); candidates beyond the cap are recorded as aread_cappedlimitation. An unread candidate in the top 10 refuses the claim and names it.- 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.
| Need | Single-repo code graph | CompareGraph |
|---|---|---|
| Compare several repos on one feature list | no, one repo per index | family, relate, matrix |
| Keep the evidence beside the verdict | no | a claim stores path:start-end and a content hash |
| Refuse a claim it cannot support | no | has and partial need a live citation; none needs a search the engine ran |
| Show what changed after the code moved | no | check marks a moved citation stale; the matrix shows unknown* |
| Keep a trail of who said what | no | claims and decisions are append-only |
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
- The engine never calls a model. Every score, band, description and candidate is computed from stored facts.
- A claim needs a citation that resolves now.
hasandpartialneed--at path:start-endmatching a stored node.noneneeds--searchedterms that find nothing, or the graph check. Otherwise the engine refuses or writesunknown. - 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. 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.
| Skill | One line |
|---|---|
using-comparegraph |
Entry point: which skill applies, the order of the workflow, the habits that keep verdicts honest. |
adding-a-clone |
Register a clone as a comparator or the root, parse it, verify the build. |
defining-a-family |
Write a pack, seed one with family propose, reload it safely. |
mapping-features |
Find candidate evidence and score relatedness. Candidates are leads, never verdicts. |
writing-a-claim |
Record has, partial, none or unknown with citations that resolve now. |
recording-a-decision |
Record a person's adopt, reject or park with their name and reason. |
reading-the-vault |
Read the matrix, the vault and the JSON export, and read gaps correctly. |
Compare screens, not only code
The same idea as the feature table, for what a person sees. A separate probe captures each screen of your product and of the products you compare against into plain files; CompareGraph reads those files and answers in numbers, not adjectives. It reads files only: it never opens a browser or a network connection.
Four layers, from what can be counted to what has to be walked:
- Structure. Twelve clutter metrics, E1 to E12 (navigation columns before the content, primary actions, machine words on screen, and so on), each with a limit per kind of screen and a pass or fail.
- Layout grammar. Which regions the page has (rail, sidebar, list, main, panel, top bar), where the primary action sits, where the content starts.
- Style. The design system as measured: type sizes, weights, colours, spacing steps, radii, shadows, density, low-contrast text. A product's system is the union over its screens, held to a target such as at most 6 type sizes and 12 colours.
- Menu tree, flows and journeys. The navigation as a tree (places, depth, duplicates, dead items), a task as steps and dead ends, and an end-to-end goal as clicks, decisions and time to the first useful thing.
Screenshots are context for people and for a judge, kept by content hash and compared by a 64-bit difference hash. They are never the gate.
Why two runs agree (the determinism protocol):
- Capture key. A capture is product@version / screen / state / viewport / seat / locale / theme, never a URL; screens come from one versioned registry so products line up.
- Frozen environment. Clock, time zone, locale, scale, motion, fonts and a three-read stability check are fixed; a page that will not settle is marked
unstable, not kept silently. - Seeded data. Every state (empty, populated, error, long) is made from a versioned fixture, not read live.
- Two hashes.
domHashidentifies what was shown, exactly; the image hash identifies the picture, within 4 bits. - Run twice, each run in its own root.
ui verify --root-a DIR --root-b DIRcompares two runs and fails on any difference, including a changed list of failed network calls (net.failed); timings are shown, never compared. Two runs written into one root share evidence paths, so the one-root form (ui verify RUN_A RUN_B) refuses runs that share a file.
Quick start, against a folder that holds a ui/ tree (--ui-root):
comparegraph ui show ours room --ui-root ./captures # the 12 metrics, layout, style, the image
comparegraph ui diff room --ours ours --ref theirs --ui-root ./captures # layout and style differences in words
comparegraph ui matrix FAMILY --ui-root ./captures # one family's rows against every product
comparegraph ui nav-diff --ours ours --ref theirs --ui-root ./captures # menu tree against menu tree
comparegraph ui graph ours --ui-root ./captures # interaction graph: depth, orphans, dead actions, cycles
comparegraph ui path ours room inbox --ui-root ./captures # shortest click path between two screens
comparegraph ui graph-diff --ours ours --ref target --ui-root ./captures # against the intended graph built from target-nav.json
comparegraph ui journey j1 --ui-root ./captures # who completes the goal, in how many clicks
comparegraph ui matrix FAMILY --net --ui-root ./captures # also: captures with failed network calls
comparegraph ui matrix FAMILY --devices desktop-1440,ipad-portrait,iphone,android --ui-root ./captures # one column per device, each cell with its support class
comparegraph ui verify --root-a ./run1 --root-b ./run2 # the determinism gate: run twice (own root each), diff
The file formats are in docs/decisions.md; fixtures/ui-contract/ is a real probe output that the tests read with every verb.
Using it
Four pages under docs/ hold the reference; each is a few clicks from here.
What you get
Screens. The same four-layer answer for a page of your product against a reference: metrics, layout, style, menu tree and journeys, from capture files (above).
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.
CompareGraph MCP questions
How do I add CompareGraph MCP to Claude Code?
Run claude mcp add comparegraph -- npx -y @massrelayai/comparegraph in your terminal. Add --scope user to make it available in every project.
How do I add CompareGraph MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does CompareGraph use AI models or the network?
No, the engine never calls an AI model or the network; it reads clones locally and computes results from stored facts.
What kind of evidence does the tool provide for its answers?
Each answer includes an evidence class such as observed, derived, inferred, or unknown, along with a list of limitations.
Can I use CompareGraph with my coding agent?
Yes, it can be wired up to various agents like Claude Code, Cursor, and Windsurf through MCP.