Get started with Roam

Why Roam is different

Roam adds a local map and static checks to the tools your agent already uses. Three useful parts of that workflow:

• Credential-free. No account, no API key, no cloud login. pip install and run.
• Local analysis by default. Source parsing and analysis stay on the machine with no automatic telemetry or upload. Run roam index --force once while connected to prewarm parser binaries before air-gap use; avoid the explicit network triggers listed on the security page.
• Optional records of checks. The run ledger and proof-bundle workflow, when configured, can save a portable ChangeEvidence packet. Read what the record contains and which checks are missing. A signed record does not prove who acted, complete coverage, or permission to ship.

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 and try your first checks

pip install "roam-code[mcp]"

cd /path/to/your/repo
roam init

roam health

roam preflight <symbol>

Historical example. The v13.2 fresh-install smoke transcript, 18 May 2026 records commands run in a clean environment against a three-file synthetic project. It is a dated example, not a test of the current package or your installation.

Keep the index current

roam index                   # refresh source and Git metadata
roam doctor                  # check environment and index readiness
roam health --explain         # inspect architectural score contributions

Run roam index after a pull, branch switch, or commit. Unchanged files reuse existing source data, while Git history is checked even when a commit leaves file contents unchanged. For a full rebuild, use roam index --force. Preserve .roam/ project state and let an active writer finish before recovery; see index troubleshooting.

What's next

Pick the path that matches your role:

• Follow a worked example: From a first scan to a saved review record — install → health → preflight → critique → a configured ChangeEvidence packet. Setup time varies by project.
• Agent integration: Follow your client's setup guide — preview and apply the configuration, restart the connection, then check a result in your project.
• Command workflows: Command Reference — examples and command families. Use roam <command> --help for exact flags and roam surface --json for the complete inventory.
• 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.
• Try your own repository: Free local sample — roam pr-replay --tier sample checks the HEAD~5..HEAD commit range by default, not five PR identities. It does not rerun tests. For founder review and a walk-through of a larger scope, ask about a paid report; scope and terms are agreed before work begins.

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          # indexed callers to investigate before editing
roam preflight auth_login       # pre-edit report: callers, tests, complexity and fitness
roam test-gaps --changed        # static test gaps for unstaged changes

3. Working in tests (pytest projects)

pytest fixtures depend on each other through their parameter names. Indexing records those fixture dependencies, so your agent can trace the tests affected by a fixture change. roam pytest-fixtures shows 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 health --gate

These use the built-in checks and your configured quality gates. To evaluate custom YAML rules, first place reviewed rules in your project's .roam/rules/, then run roam rules. The rules/community directory belongs to the Roam source checkout; installing the package does not add it to your project.

5. Integrate with your agent

roam mcp-setup claude-code          # preview the configuration
roam mcp-setup claude-code --write  # write or safely merge ./.mcp.json
roam mcp --list-tools-json          # inspect this local process's inventory

Restart the client after changing its configuration or preset, then inspect the connected server's tools in that client. A local inventory does not establish which installation the client launched. See the client-specific setup steps for executable paths, working directories, and connection checks.

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)

Whole-repository checks for an indexed CI checkout:

roam init
roam check-rules --severity error
roam --sarif health --gate

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

For test-gap analysis of a committed pull request, establish its exact base and head commits, obtain the changed file paths from that range, and pass those paths to roam --json test-gaps. --changed selects unstaged changes; a clean CI checkout normally has none. Confirm Git succeeded and the selected scope before interpreting an empty report. Static test mappings do not run tests; keep your project's test command in CI.

Example: roam + CodeQL co-deploy

Run Roam alongside GitHub CodeQL and upload both SARIF streams to Code Scanning. Inspect the findings and their overlap; two reports do not establish complete coverage. See the sample workflow: src/roam/templates/ci/roam-sarif-with-codeql.yml.

Troubleshooting