Tutorial

Getting Started with Roam

Zero to a working structural index in 10 minutes, then through the daily workflows: impact analysis, safety checks, and agent integration.

Tutorial scope: local CLI usage, MCP setup, and CI gate setup. Non-goal: cloud hosting or SaaS deployment.

Quick Path (10 minutes)

Step 1: Install

pip install roam-code
pip install "roam-code[mcp]"  # optional MCP support

Requires Python 3.9+. Also works with pipx install roam-code and uv tool install roam-code.

Step 2: Initialize in your repo

cd /path/to/repo
roam init

Creates .roam/index.db, fitness rules, and a CI workflow.

Step 3: Ask your first structural question

roam context UserService
roam impact UserService
roam retrieve "where does login validate sessions"

Get ranked reading order and blast radius before changing code. roam retrieve returns budget-bounded spans ranked by personalised PageRank, clone signal, and lexical match.

Step 4: Run a pre-change check

roam preflight UserService
roam health

Checks complexity, coupling, test impact, and architecture risk.

Step 5: Verify the patch

git diff | roam critique
# clones-not-edited check + blast-radius caller count
# Exit 5 on high-severity findings — gate-able in CI.

For the killer clones-not-edited check, run roam clones --persist once to populate the clone tables.

Step 6: Plan parallel agent work

roam fleet plan "split the auth refactor across 4 agents" \
  --n-agents 4 --adapter composio \
  --output .roam-fleet.json

Graph-aware partition (Louvain + co-change + PageRank anchors) emits a .roam-fleet.json envelope consumable by Composio Agent Orchestrator, GitHub Copilot CLI /fleet, or any raw fleet runtime.

Step 7: Sign a Code Graph Attestation

roam taint
roam cga emit --include-taint --sign --key cosign.key
roam cga verify .roam/attestations/<sha>.intoto.json

Emits an in-toto v1 statement with the roam-code.dev/CodeGraph/v1 predicate type — Merkle root over symbol fingerprints, edge bundle digest, and (with --include-taint) OpenVEX-shaped reachability claims. Cosign signing optional; skips gracefully when the binary is missing.

Step 8: One-phrase intent for everything else

roam ask "is it safe to delete UserSession"
roam ask "where does login validate sessions"
roam ask --list

roam ask classifies a free-form question and dispatches the right composition of preflight/retrieve/critique/fleet/understand. No need to memorise the 202-command surface.

Hands-on Workflow

1. Explore the codebase

roam understand
roam search auth
roam symbol src/auth/service.py

2. Estimate change risk

roam impact auth_login
roam preflight auth_login
roam test-gaps --changed

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
roam mcp --list-tools
ROAM_MCP_PRESET=core roam mcp

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.

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
Rule results too noisy	`roam check-rules --profile ai-code-review`	Applies tuned thresholds and severities