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.

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)`:

  Blast radius:     1847 symbols in 382 files                [CRITICAL]
  Affected tests:   617 direct, 962 transitive               [OK]
  Complexity:       cc=30, nest=4                            [CRITICAL]
  Coupling:         2 files often change together            [MEDIUM]
  Conventions:      no violations                            [OK]

  Overall risk: CRITICAL
  Risk driver:  complexity (cc=30, CRITICAL)

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

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 (alpine-based)
docker build -t roam-code .
docker run --rm -v "$PWD:/workspace" roam-code index
docker run --rm -v "$PWD:/workspace" roam-code health

What's New

v13.4 (released 2026-05-21) — Perf wave + Pattern-1 stabilisation + assurance hardening. Major detector speed-ups (clones 43.8s → 13.1s, intent 66s → 12s, doc-staleness 93s → 19s, sbom 30s → 9s — all byte-identical output), 17 commands now emit isError/status on error envelopes + 11 commands route their argless --json path through a proper envelope (Pattern-1C drift-guards added), a persisted per-snapshot spectral gap powering a real roam forecast failure budget, MCP prompt-injection marker scan on tool-call egress, release supply-chain hardening (PEP 740 attestations, tag-bound artifacts), and large false-positive cuts in feature-envy / shotgun-surgery / god-components. Full diff in CHANGELOG.md.

Full release notes in CHANGELOG.md.

Best for

• Agent-assisted coding — structured answers that cut tokens vs raw file exploration
• Large codebases (100+ files) — graph queries beat linear search at scale
• Architecture governance — health scores, CI quality gates, budget enforcement, fitness functions
• Safe refactoring — blast radius, affected tests, pre-change safety checks, graph-level editing
• Multi-agent orchestration — partition codebases for parallel agents with conflict-aware planning
• Security analysis — vulnerability reachability, auth gaps, CVE path tracing, taint analysis
• Algorithm optimization — detect O(n²) loops, N+1 queries, and 32 other anti-patterns with suggested fixes

When NOT to use Roam

• Real-time type checking — use an LSP (pyright, gopls, tsserver). Roam is static and offline.
• Small scripts (<10 files) — read the files directly.
• Pure text search — ripgrep is faster for raw string matching.

Core commands

Lead with the 5 verbs. The 5 core commands cover ~80% of agent workflows: understand, context, retrieve, preflight, critique. The remaining ~236 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is 241 commands (234 canonical + 7 aliases) organised into 7 categories (aliases for muscle memory: math → algo, churn → weather, digest / snapshot / trend → trends, onboard → understand, refs → uses), but you don't need to know that to start.

The full surface spans 7 categories — Getting Started, Daily Workflow, Codebase Health, Architecture, Exploration, Reports & CI, and Multi-Repo Workspace. Run roam --help for the 5-verb core, roam --help-all for every command name, and roam surface --json for the machine-readable inventory. Every command accepts roam --json <cmd> for structured output and roam --sarif <cmd> for CI integration (SARIF 2.1.0, honoured by 37 commands).

A few representative commands beyond the core five:

• Health & architecture: roam health (0-100 score), roam weather (churn × complexity hotspots), roam smells (24 deterministic detectors), roam algo (34-task anti-pattern catalog), roam clusters / roam layers / roam cycles.
• Change safety: roam impact <symbol> (blast radius), roam diff (uncommitted-change blast radius), roam pr-risk (0-100 PR risk), roam diagnose <symbol> (root-cause ranking).
• Backend quality: roam n1 (N+1 queries), roam auth-gaps, roam missing-index, roam over-fetch, roam taint (graph-reach taint, 10 rule packs).
• Index-aware search: roam search <pattern>, roam grep <pattern> (grep + reachability + PageRank), roam uses <name> (graph-precise references, no string-literal false positives).
• Multi-agent: roam orchestrate --agents N (conflict-aware partitioning), roam fleet plan, roam lease (parallel-agent coordination).

Walkthrough

$ roam understand
Tech stack: Python (flask, jinja2, werkzeug)
Architecture: Monolithic — 3 layers, 5 clusters
Key abstractions: Flask, Blueprint, Request, Response
Health: 78/100 — 1 god component (Flask)
Entry points: src/flask/__init__.py, src/flask/cli.py

$ roam file src/flask/app.py            # file skeleton: definitions + signatures + health
$ roam deps src/flask/app.py            # what imports this file
$ roam weather                          # hotspots ranked by churn × complexity
$ roam health                           # composite 0-100 + god components / cycles / layer violations
$ roam context Flask                    # AI-ready context: files to read with line ranges
$ roam preflight Flask                  # pre-change gate: blast radius + tests + complexity + fitness
$ roam split src/flask/app.py           # internal symbol groups + extraction suggestions
$ roam why Flask url_for Blueprint      # role classification (Hub/Bridge/Core) + reach + risk
$ roam health --gate                    # CI quality gate (exit 5 on failure)

Integration with AI coding tools

Roam is designed to be called by coding agents. Instead of repeatedly grepping and reading files, the agent runs one roam command and gets a verdict-first envelope. roam preflight (above) replaces grep+read+test-impact+complexity+fitness in one ~3KB call; roam health rolls the whole codebase into one score:

$ roam health
VERDICT: Fair codebase (75/100) — 47 critical, 9 warnings, focus: god_components

Health Score: 75/100  |  Tangle: 0.0% (7/33395 symbols in cycles)
Propagation Cost: 0.1%  |  Algebraic Connectivity: 0.0074

Health: 67 issues — 47 CRITICAL, 9 WARNING, 19 INFO
  Breakdown: cycles [1 CRITICAL, 1 WARNING], god [31 CRITICAL, 8 WARNING, 11 INFO], bottlenecks [15 CRITICAL]

Top CRITICAL issues (run `roam --detail health` for the full breakdown):
  cycle (5 symbols): _COMMANDS, complete, _reconstruct_command
  god component: path (prop, degree=2408)

The verdict line works alone — an agent that reads nothing else still knows where to look. Pipe --json for the structured envelope your agent consumes.

Fastest setup: point your agent at Roam by writing instructions into its config file.

roam describe --write               # auto-detects CLAUDE.md, AGENTS.md, .cursor/rules, etc.
roam describe --agent-prompt        # compact ~500-token prompt — copy-paste into an existing config
roam minimap --update               # inject/refresh an annotated codebase minimap (won't touch other content)

This teaches the agent which command fits each situation: roam preflight before changes, roam context for files to read, roam diagnose for debugging.

MCP Server

Roam includes a Model Context Protocol server for direct integration with MCP-aware tools.

pip install "roam-code[mcp]"
roam mcp

Default preset: core (58 tools: 57 core + roam_expand_toolset meta-tool).

227 tools span seven presets (core, review, refactor, debug, architecture, compliance, full); core stays narrow to keep the prompt tight. Most tools are read-only index queries; side-effect tools are explicitly annotated. Set ROAM_MCP_PRESET=full roam mcp for the complete toolset.

Cold-start envelope. Any wrapper that can't complete normally — missing index, stale index, partial failure — returns one canonical structured envelope (status, error_code, summary.verdict, hint, next_command) instead of hanging or emitting empty output. Agents always get an actionable signal, never a silent failure.

MCP runtime security. Three controls run at the wrapper boundary inside the server, protecting every client even with no gateway present: egress secret-redaction, mode-gated policy_decision enforcement (opt-in shadow-mode via ROAM_MODE_DRY_RUN), and HMAC-linked decision receipts bound into the signed run ledger. Gateway integrators: see dev/MCP-SECURITY-POSTURE.md.

See Using Roam via MCP for the first-run flow and canonical agent sequence.

Core preset tools: roam_affected_tests, roam_alerts, roam_ask, roam_audit_trail_conformance_check, roam_audit_trail_export, roam_audit_trail_verify, roam_batch_get, roam_batch_search, roam_catalog, roam_complete, roam_complexity_report, roam_context, roam_critique, roam_dead_code, roam_deps, roam_diagnose, roam_diagnose_issue, roam_diff, roam_disambiguate, roam_dogfood, roam_explore, roam_fetch_handle, roam_file_info, roam_fleet_plan, roam_for_bug_fix, roam_for_new_feature, roam_for_refactor, roam_for_security_review, roam_health, roam_impact, roam_metrics_push, roam_oracle_is_clone_of, roam_oracle_is_reachable_from_entry, roam_oracle_is_test_only, roam_oracle_route_exists, roam_oracle_symbol_exists, roam_pr_analyze, roam_pr_comment_render, roam_pr_risk, roam_preflight, roam_prepare_change, roam_py_modern, roam_py_types, roam_retrieve, roam_review_change, roam_rules_validate, roam_search_symbol, roam_session_metrics, roam_syntax_check, roam_taint_classify, roam_test_impact, roam_timeline, roam_trace, roam_understand, roam_uses, roam_validate_plan, roam_why_fail.

{ "mcpServers": { "roam-code": { "command": "roam", "args": ["mcp"] } } }

Go deeper

Pick the path that matches your role:

• 5-min demo (CTO/CISO/dev-tools-lead): The Canonical Demo — install → health → preflight → critique → signed ChangeEvidence packet, five commands, no laptop egress.
• Developer tutorial (15 min): Getting Started — install, index, query, ship.
• Agent integration: roam mcp-setup claude-code (or cursor, continue) — then Using Roam via MCP for the cold-start envelope and canonical agent loop.
• Full surface: Command Reference — every command, flag, and JSON envelope.
• Architecture: How it fits together — graph, findings registry, run ledger, evidence compiler.

CI/CD integration

All you need is Python 3.10+ and pip install roam-code.

# .github/workflows/roam.yml
name: Roam Analysis
on: [pull_request]

jobs:
  roam:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: Cranot/roam-code@main
        with:
          commands: health
          gate: "score>=70"
          sarif: true
          comment: true

roam init auto-generates this workflow. The Action accepts commands, gate (quality-gate expression, exit 5 on failure), sarif (upload to GitHub Code Scanning), comment (sticky PR comment), cache, and changed-only (incremental mode).

SARIF output. 37 commands honour the global --sarif flag (health, complexity, dead, smells, clones, vulns, taint, secrets, n1, …). Minimal upload:

- run: roam --sarif health > roam-health.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: roam-health.sarif

For GitLab / Jenkins / Azure / Bitbucket templates, severity gates, and upload guardrails, see docs/ci-integration.md.

Paid layers (free CLI stays Apache 2.0)

The CLI is Apache 2.0, fully local, zero-API-key, and never expires. Three optional paid layers build on the same engine:

• Roam Review — hosted PR bot for AI-generated changes, built on roam pr-analyze. CodeRabbit/Greptile review PR semantics; Roam Review reads the graph (who calls the changed symbol, which layer it sits in) and emits a portable ChangeEvidence packet. The CLI engine is a working CI gate today: git diff main..HEAD | roam pr-analyze --gate (exit 5 on BLOCK).
• Roam Cloud — opt-in metrics history with no source upload. roam metrics-push sends a summary-only payload (numerical metrics, paths or SHA-256 hashes, identifier names) — never source-code bodies. Inspect the exact payload with --dry-run.
• PR Replay — one-shot paid audit of your last 30/90 merged PRs: a written structural-review report plus a founder walk-through. Free DIY sample via roam pr-replay --tier sample.

Early access — email hello@roam-code.com. Full pricing at https://roam-code.com/pricing.

Language Support

Tier 1 — Full extraction (dedicated parsers)

Tier 2 languages (and .jsonc / .mdx) get basic symbol extraction via a generic tree-sitter walker.

Performance

After the first full index, roam index only re-processes changed files (mtime + SHA-256 hash). Detailed indexing benchmarks across Express / Axios / Vue / Laravel / Svelte live in benchmarks/.

How It Works

Codebase
    |
[1] Discovery ──── git ls-files (respects .gitignore + .roamignore)
[2] Parse ──────── tree-sitter AST per file (28 languages)
[3] Extract ────── symbols + references (calls, imports, inheritance)
[4] Resolve ────── match references to definitions → edges
[5] Metrics ────── adaptive PageRank, betweenness, cognitive complexity, Halstead
[6] Algorithms ── 34-task anti-pattern catalog (O(n^2) loops, N+1, recursion, async)
[7] Git ────────── churn, co-change matrix, authorship, Renyi entropy
[8] Clusters ───── Louvain community detection
[9] Health ─────── per-file scores (7-factor) + composite score (0-100)
[10] Store ─────── .roam/index.db (SQLite, WAL mode)

Exclude paths with a .roamignore file (full gitignore syntax) or roam config --exclude "*.proto". For the graph algorithms (Personalized PageRank for blast radius, Tarjan SCC, Louvain, Fiedler bisection, Mann-Kendall trend detection, …) and the weighted-geometric-mean health score, see the Architecture guide.

How Roam Compares

roam-code is the only tool that combines graph algorithms (PageRank, Tarjan SCC, Louvain clustering), git archaeology, architecture simulation, and multi-agent partitioning in a single local CLI with zero API keys.

Key Differentiators

• vs AI IDEs (Cursor, Windsurf, Augment): roam-code provides deterministic structural analysis. AI IDEs use probabilistic embeddings that can't guarantee reproducible results.
• vs AI Agents (Claude Code, Codex CLI, Gemini CLI): these agents read files one at a time. roam-code pre-computes relationships so agents get instant answers about architecture, blast radius, and dependencies.
• vs SAST Tools (SonarQube, CodeQL, Semgrep): SAST tools find bugs and vulnerabilities. roam-code understands architecture — how code is structured, where it's coupled, and what breaks when you change it. Complementary, not competitive.
• vs Code Search (Sourcegraph/Amp, Greptile): text search finds where code is. roam-code understands why code matters — which functions are central, which modules are tangled, which files are high-risk.

FAQ

Does Roam send any data externally? No by default — zero telemetry, zero analytics, zero update checks. The single outbound surface is roam metrics-push: opt-in, summary metrics only, prints its exact payload locally under --dry-run. Source-code bodies never leave the machine.

Can Roam run in air-gapped environments? Yes. Once installed, no internet access is required.

Does Roam modify my source code? Read-only by default. Creates .roam/ with an index database. roam mutate (move/rename/extract) defaults to --dry-run; pass --apply explicitly to write changes.

How does Roam handle monorepos and multi-repo projects? Monorepos: indexes from the root; batched SQL handles 100k+ symbols. Multi-repo: roam ws init <repo1> <repo2> builds a workspace overlay DB for cross-repo API edges, then roam ws resolve / ws context / ws trace work across repos.

Is Roam compatible with SonarQube / CodeScene? Yes — they coexist in the same CI pipeline. SARIF output uploads to GitHub Code Scanning.

Does Roam satisfy SOC 2 / ISO 42001 / EU AI Act on its own? No. Roam maps to controls and produces supporting evidence — the signed ChangeEvidence packet, HMAC-chained run ledger, and audit-trail records answer the eight evidence questions a reviewer asks after an AI-assisted change. Roam does not certify; your auditor still owns that step.

What's the difference between the free CLI and Roam Review / Cloud / PR Replay? The CLI is Apache 2.0, fully local, and never expires. Roam Review is a hosted PR bot, Roam Cloud is opt-in metrics history with no source upload, PR Replay is a one-shot paid audit. All three are layers on top of the same engine.

Limitations

• Static analysis primarily — can't trace dynamic dispatch, reflection, or eval'd code. Runtime trace ingestion (roam ingest-trace) adds production data but requires external trace export.
• Import resolution is heuristic — complex re-exports or conditional imports may not resolve.
• Limited cross-language edges — Salesforce, Protobuf, REST API, and multi-repo edges are supported, but not arbitrary FFI.
• Tier 2 languages get basic symbol extraction only via the generic tree-sitter walker.
• Large monorepos (100k+ files) may have slow initial indexing.

Troubleshooting

Update / Uninstall

# Update
pipx upgrade roam-code        # or: uv tool upgrade roam-code / pip install --upgrade roam-code

# Uninstall
pipx uninstall roam-code      # or: uv tool uninstall roam-code / pip uninstall roam-code

Delete .roam/ from your project root to clean up local data.

Contributing

git clone https://github.com/Cranot/roam-code.git
cd roam-code
pip install -e ".[dev]"   # includes pytest, ruff
pytest tests/              # all test cases must pass

Good first contributions: add a Tier 1 language (see go_lang.py or php_lang.py as templates), improve reference resolution, add benchmark repos, extend SARIF converters, add MCP tools. Please open an issue first to discuss larger changes.

License

Apache 2.0