Getting Started with Roam

Why Roam is different

IDE-surface tools (Cursor, Cody, Windsurf, Continue) and semantic reviewers (CodeRabbit, Greptile, Qodo, SonarQube) help humans write or review code through hosted accounts and editor surfaces. Roam is the local-CLI surface that gates the change before the diff and emits portable proof after. Three properties no competitor combines today:

• Credential-free. No account, no API key, no cloud login. pip install and run.
• Zero network egress. Your source code never leaves the machine. Air-gapped repos work the same as cloud repos.
• Tamper-evident ChangeEvidence packets. Every AI-assisted change compiles into one portable evidence packet (HMAC-chained run ledger + signed Code Graph Attestation + signed PR bundle) that answers the eight evidence questions.

Underneath sits a SQLite-backed graph of symbols, calls, imports, architecture layers, git history, smells, clones, and algorithmic patterns across 28 languages. Side-by-side vendor research on /compare.

Install + first three commands

pip install "roam-code[mcp]"

cd /path/to/your/repo
roam init

roam health

roam preflight <symbol>

Verify it yourself. Fresh-install smoke transcript — a verbatim capture of these four commands run against a clean venv and a three-file synthetic project. Copy-paste reproducible; no synthetic output.

What's next

Pick the path that matches your role:

• See it run end-to-end: The 5-minute canonical demo — install → health → preflight → critique → signed ChangeEvidence packet, the moat arc in one sitting.
• Agent integration: roam mcp-setup claude-code (or cursor, windsurf, vscode, gemini-cli, codex-cli) — then see Using Roam via MCP for the cold-start envelope and canonical agent loop.
• Full surface reference: Command Reference — every command, every flag, every JSON envelope.
• Architecture deep-dive: Architecture — how the index pipeline, findings registry, agent-OS substrate, and evidence compiler fit together.
• Agent contract: Agent Contract — context before edit, impact before delete, critique before merge, simulate before refactor, math before optimise.
• Want a worked example on your own repo? Run a paid PR Replay — we replay your last 5 PRs through Roam, return a signed evidence packet plus a written analyst report, and your spend converts to Review credit if you continue with the hosted product.

Hands-on Workflow

1. Explore the codebase

roam understand                 # high-level tour: layers, hot paths, frameworks
roam search auth                # find symbols matching a pattern
roam symbol auth_login          # callers + callees for one symbol
roam file src/auth/service.py   # file skeleton (symbols + line ranges)

2. Estimate change risk

roam impact auth_login          # blast radius: what breaks if this changes
roam preflight auth_login       # pre-edit gate: blast + tests + complexity + fitness
roam test-gaps --changed        # tests missing for the current diff

3. Working in tests (pytest projects)

pytest fixtures depend on each other through their parameter names. The relationship is invisible to call-graph analysis, so renaming a low-level fixture can break tests several files away with no edge to follow. roam pytest-fixtures materialises the chain.

roam pytest-fixtures            # project summary
roam pytest-fixtures user       # what depends on `user`
roam pytest-fixtures --unused   # orphaned fixtures
roam impact db                  # blast radius traverses fixture edges

4. Enforce quality and governance

roam check-rules
roam rules --rules-dir rules/community
roam health --gate

5. Integrate with your agent

roam mcp-setup claude-code      # writes ./.mcp.json (or --write to merge)
roam mcp --list-tools           # 227 tools registered; 57 in the default `core` preset
ROAM_MCP_PRESET=core roam mcp   # start the server (stdio transport)

Supported clients: claude-code, cursor, windsurf, vscode, gemini-cli, codex-cli. Run roam mcp-setup with no argument to print the full list and config-path per client.

Once the MCP server is wired up, see Using Roam via MCP for the cold-start envelope, the canonical agent flow, and the slow-tool patterns.

CI Example (GitHub Actions)

Minimal gate pipeline:

roam init
roam check-rules --severity error
roam --sarif health --gate
roam --json test-gaps --changed

Use --sarif output for Code Scanning annotations and --json envelopes for stable machine parsing.

Example: roam + CodeQL co-deploy

Run roam alongside GitHub CodeQL and upload both SARIF streams to Code Scanning — coverage is additive, not redundant. See the sample workflow: src/roam/templates/ci/roam-sarif-with-codeql.yml.

Troubleshooting