Tutorial

Getting Started with roam

This walkthrough takes you from zero to a working structural index, then through 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

Get ranked reading order plus blast radius before changing code.

Step 4: Run a pre-change check

roam preflight UserService
roam health

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

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. Enforce quality and governance

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

4. 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