Skip to content

Tutorial

# Getting Started with Roam

Ten minutes from `pip install` to a verdict on whether your next edit is safe.

Roam is the local codebase intelligence layer that lets AI coding agents earn the right to change code — and prove they did. Credential-free, zero network egress by default (opt-in `metrics-push` is the only outbound surface), tamper-evident `ChangeEvidence` packets. Cursor and Cody log the session; Roam gates the change and emits proof.

## 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

### Step 1: Install

    pip install "roam-code[mcp]"

Requires Python 3.10+. `pipx install roam-code` and `uv tool install roam-code` work too. Drop `[mcp]` if you only want the CLI.

### Step 2: Index the repo

    cd /path/to/your/repo
    roam init

One-time, ~30 seconds on most repos. Creates `.roam/index.db`, fitness rules, and a CI workflow.

### Step 3: Check repo health

    roam health

Composite 0-100 score across complexity, cycles, dark-matter coupling, dead code, and architecture drift. Add `--sarif` for GitHub Code Scanning, `--gate` to fail CI below a threshold.

### Step 4: Gate the next change

    roam preflight <symbol>

Blast radius + affected tests + complexity + architecture rules before you edit. The single highest-leverage call agents make before touching code.

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

Symptom | Command | Expected fix
--- | --- | ---
Command says index missing | `roam init` | Creates/refreshes `.roam/index.db`
Environment diagnostics unclear | `roam doctor` | Shows PASS/FAIL checks with remediation hints
MCP client cannot see tools | `roam mcp --list-tools` | Verifies server + current preset/tool exposure
Tool hangs from MCP client | `roam init` | See Using Roam via MCP — likely missing initial index; run `roam init` first
Rule results too noisy | `roam check-rules --profile ai-code-review` | Applies tuned thresholds and severities