roam-code
The local codebase intelligence layer that lets AI coding agents earn the right to change code — and prove they did.
Credential-free · 100% local by default (opt-in metrics-push is the only outbound surface) · tamper-evident ChangeEvidence packets · Apache 2.0 · runs entirely on your machine
267 commands · 243 MCP tools (16 in the default core preset) · 28 languages
Why Roam is different
Cursor, Cody, Aider, and Windsurf are human-first IDE surfaces that log a session. Roam is an agent-first CLI surface that gates the change and emits proof. Four properties no competitor combines today:
- Credential-free. No account, no API key, no cloud login.
pip install and run.
- 100% local by default. Source code never leaves the machine; air-gapped repos work like cloud repos. The single outbound surface (
roam metrics-push) is opt-in, summary-only, and prints its exact payload under --dry-run.
- Tamper-evident
ChangeEvidence packets. Each AI-assisted change compiles 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 answers 7 of 8 today; the remaining approvals question surfaces as producer_not_available, never silently dropped. Cursor logs the run; Roam proves the change.
- 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 — <0.5s per query, plain-ASCII output, --json and --sarif envelopes for agents and CI.
| 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; full indexing-rate harness in benchmarks/. Exact numbers vary with repo size, agent prompt, and model.
Install + first four commands
Ten 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, 1847 symbols in blast radius
Pre-flight check for `open_db (src/roam/db/connection.py:799)`:
