<div align="center">

roam-code

The local codebase intelligence layer that lets AI coding agents earn the right to change code — with evidence for what was checked.

_{Credential-free · local analysis with no automatic source-code or telemetry upload · tamper-evident ChangeEvidence packets · Apache 2.0 · runs on your machine}

<!-- BEGIN auto-count:readme-headline-counts -->

_{285 commands · 244 MCP tools (17 in the default core preset) · 28 languages}

<!-- END auto-count:readme-headline-counts -->

_{<a href="https://roam-code.com/pricing"><b>Paid layers →</b></a>  <b>PR Replay</b> audit $2,500 Team / $6,000 Deep, available now  ·  <b>Roam Review</b> from $99/mo flat — no per-seat pricing  ·  <b>Roam Cloud</b> $19/repo/mo  ·  Review and Cloud are early access. The CLI below is Apache 2.0 and free forever.}

</div>

---

Jump to — Why Roam · Install · The Compiler · Core commands · MCP server · AI-tool integration · Roam Guard (PR gate) · Performance · Compare · Pricing · FAQ

---

Why Roam is different

METR and FrontierCode both point at the same gap: passing tests is not the same as mergeable code. Roam is an agent-first CLI surface that gives the agent local graph facts before it edits, gates risky changes, and emits scoped evidence after the run. In the agent/review tools surveyed as of 2026-06-12, the differentiator is this combination:

• Credential-free. No account, no API key, no cloud login. pip install and run.
• Local analysis with an explicit network boundary. Source parsing, indexes, findings, and evidence generation stay on the machine; Roam sends no automatic telemetry or update checks. A cold tree-sitter-language-pack grammar cache downloads one checksum-verified platform bundle and retains it locally. Additional network-capable commands and flags are opt-in and inventoried in docs/network-boundary.md, including their destinations and payload classes.
• Tamper-evident ChangeEvidence packets. A Roam-guided change can compile into one portable packet — HMAC-chained run ledger + signed Code Graph Attestation + signed PR bundle — answering eight questions: who acted, what authority existed, what context was read, what changed, what could break, what policy applied, what verified it, who accepted risk. PR Replay maps those eight questions today: structural change/risk/policy axes are in scope, context and verification are partial, and missing identity/authority/approval evidence is disclosed instead of invented. Cursor logs the run; Roam records and verifies the evidence its producers captured.
• MCP runtime security at the wrapper boundary. Every MCP response is scrubbed for secrets on egress, gated against the active mode (read_only / safe_edit / migration / autonomous_pr) with a closed-enum policy_decision, and each decision receipt is HMAC-linked into the signed run ledger. Inside-server controls; the gateway layer (Interlock / Lasso / Portkey) composes on top — see dev/MCP-SECURITY-POSTURE.md.

Underneath sits a SQLite-backed graph of symbols, calls, imports, layers, git history, runtime traces, smells, clones, security flows, and algorithmic patterns across 28 languages — the same local facts queried before, during, and after a change.

Dependency-aware, not string-based. Roam knows Flask has 47 dependents and 31 affected tests; grep knows it appears 847 times. One command replaces 5-10 tool calls, with terminal-friendly UTF-8 output and --json / --sarif envelopes for agents and CI. See Performance for timings.

| | Without Roam | With Roam | |--|-------------|-----------| | Tool calls | 8 | 1 | | Wall time | ~11s | <0.5s | | Tokens consumed | ~15,000 | ~3,000 |

Illustrative — a typical agent workflow on a 200-file Python project (Flask). Reproducible smoke transcript in docs/fresh-install-smoke.md; OSS benchmark harness in benchmarks/oss-eval/. Exact numbers vary with repo size, host, agent prompt, and model.

---

Install + first four commands

About two minutes from pip install to a verdict on whether your next edit is safe.

pip install "roam-code[mcp]"          # 1. install with MCP server for Claude Code / Cursor / Continue
cd /path/to/your/repo
roam init                             # 2. index the repo into .roam/index.db (one-time, ~30s on most repos)
roam health                           # 3. composite 0-100 score: complexity, cycles, dark-matter coupling, dead code
roam preflight <symbol>               # 4. blast radius + tests + complexity + architecture rules before you edit

Python 3.10+. pipx install roam-code and uv tool install roam-code work too. Drop [mcp] for CLI-only. See docs/fresh-install-smoke.md for a verbatim transcript of these four commands against a clean venv.

Step 4 is the payoff — roam preflight on a hot symbol returns a verdict before you touch it:

$ roam preflight open_db
VERDICT: Significant risk — CRITICAL, 17922 symbols in blast radius

Pre-flight check for `open_db (src/roam/db/connection.py:1076)`:

  Blast radius:     17922 symbols in 1732 files              [CRITICAL]
  Affected tests:   681 direct, 14126 transitive             [OK]
  Complexity:       cc=5, nest=2                             [LOW]
  Coupling:         2 files often change together            [MEDIUM]
  Conventions:      no violations                            [OK]
  Fitness:          target passes; 1 rule(s) fail on sibling symbols [OK]

  Overall risk: CRITICAL
  Risk driver:  blast radius (17922 symbols in 1732 files, CRITICAL)

An agent sees the blast radius before it edits — not after the tests fail.

<details> <summary><strong>Alternate install methods + Docker</strong></summary>

pipx install roam-code                                   # isolated environment (recommended)
uv tool install roam-code                                # uv-managed tool
pip install git+https://github.com/Cranot/roam-code.git  # from source

# Docker (python:3.12-slim-bookworm base)
docker build -t roam-code .
docker run --rm -v "$PWD:/workspace" roam-code index
docker run --rm -v "$PWD:/workspace" roam-code health

Works on Linux, macOS, and Windows. Windows: if roam is not found after installing with uv, run uv tool update-shell and restart your terminal.

</details>

---

The Compiler — your agent's first token already knows the answer

You ask your agent "who calls handleSave?" and watch it grep, open three files, grep again, read a fourth — six turns and $1.30 later you get the answer the repo's call graph held all along.

Roam ships a task compiler that ends that loop. Before your prompt reaches the model, roam recognizes what kind of question it is, runs the right code-graph lookups locally (~90 ms, zero model calls), and puts the answers into the prompt: the caller list with line numbers, the git history already filtered, the source around the bug line you cited. The agent's first words can be the answer.

For Claude Code it's one command, zero configuration:

pip install "roam-code[mcp]"
cd your-repo && roam init
roam hooks claude --write     # compile-before + verify-after, wired into Claude Code

Then use claude exactly as you always do. Undo anytime with roam hooks claude --uninstall --write. Compile-time context injection is fail-open. After an edited turn, the Stop gate is deliberately fail-closed: findings, malformed output, an unavailable check, or incomplete evidence must be resolved before Claude reports completion. No-edit Q&A turns fast-exit.

What that buys you, measured head-to-head on Claude (same prompts, same repo, with and without the compiler — June 2026, 41 cells):

| Median per task | vanilla | compiled | delta | |---|---|---|---| | Agent turns (navigation/comprehension) | 6 | 1 | −83% | | Input tokens | 271K | 53K | −80% | | Cost | $1.30 | $0.48 | −63% | | Wall time | — | — | −50% |

A second run on Opus shows the same direction at smaller magnitude (−33% turns overall; the best single cell hit −88%). And the compiler knows where it doesn't help: prompts that ask the agent to write code get no envelope at all — injection there was measured as pure overhead, so it spends your tokens only where it wins.

<details> <summary><b>The full data</b> — every bench cell (including the losses), the ground-truth bug bench, and routing stats</summary>

| Task | turns | input tokens | cost | |---|---|---|---| | "where is open_db defined?" | 3 → 1 | 156K → 51K | $0.67 → $0.28 | | "which files depend on cli.py?" | 6 → 1 | 252K → 51K | $1.15 → $0.30 | | "where is the env var configured?" | 9 → 1 | 497K → 53K | $1.40 → $0.31 | | "what are the layers of this codebase?" | 5 → 1 | 271K → 50K | $1.42 → $0.41 | | "what changed in cli.py recently?" | 4 → 2 | 186K → 104K | $0.62 → $0.40 | | "explain the compiler module's architecture" | 13 → 6 | 618K → 240K | $1.85 → $1.01 | | "trace how a command becomes an MCP tool" | 12 → 8 | 464K → 303K | $1.25 → $1.01 | | security-hook comprehension (hard, multi-file) | 6 → 2 | 267K → 117K | $1.15 → $0.56 | | "what are the biggest cycles in this codebase?" (re-measured 06-11) | 6 → 1 | — | $0.65 → $0.07 | | "where is the CLI entry point?" (trivial, re-measured 06-11) | 1 → 1 | 48K → 50K | $0.21 → $0.22 | | "write a pytest for X" (generation, re-measured 06-11) | 5 → 7 | 275K → 396K | $0.61 → $0.45 |

The last two rows were the published LOSSES (trivial prompts once paid the envelope for nothing at +$0.20; generation once cost +17%). After the generation-skip lever (write-code prompts get a ~0.6 KB lean envelope or none — measured 3.5% of a 723-prompt real corpus) and the entry-point routing fix, both cells were re-measured at n=3 medians on the same model: generation flipped to a −26% cost / −18% wall win — input tokens rise (cache-read-heavy, cheap) while expensive output tokens drop −29% across more-but-cheaper turns — and the trivial cell is a tie within noise. Losses are findable because we publish them — and fixable because the compiler routes them.

Bug-fixing, ground-truth graded (a failing test must transition to passing — no LLM judging): 20 cells of planted bugs with real tracebacks — 10/10 fixed in both arms at −13% dollar cost. Read that honestly: n=10 cannot establish quality parity (the 95% interval on 10/10 spans [72%, 100%]), and the dollar saving comes with more tokens, not fewer on this task class — the envelope shifts spend into cheaper cache reads. No quality d