Documentation

How Roam thinks.

Pick the right tool for the question. Each Roam command answers a specific engineering question — match the question to the command, not the other way around.

Nine moments in an engineering workflow · zero API keys · no automatic source-code or telemetry upload · checksum-verified parser cache · tamper-evident evidence

The decision tree

The agent contract covers the five rules and the canonical JSON envelope. This page goes deeper: nine moments that come up in real work, with the four-to-five Roam commands that answer each and one example invocation per moment. If you only remember the moment, you can find the command later.

Build a local index, refresh it as code changes, and let the agent reuse its symbols and relationships. Some checks also inspect current source, Git state, or supplied records. Use --json for results an agent acts on, and keep scope, freshness, and incomplete checks visible. Configured evidence workflows can collect supported observations into a ChangeEvidence record. See architecture for the components and PR Replay for paid interpretation of an agreed scope.

1. "I'm new to this repo. What does it do?"

You've cloned a codebase you didn't write. Before reading any file, get the shape: layers, entry points, hot files, the few symbols with many indexed connections. Roam answers with a landing-pad summary, a curated tour, and a one-page minimap that fits in an agent's context window.

Commands: roam understand · roam tour · roam map · roam minimap · roam describe. 

$ roam understand
$ roam tour
$ roam minimap

2. "I have a task. What code should I read first?"

You have a feature, a bug, or a phrase like "trace login flow" or "where is the n+1?" You need ranked, budget-bounded spans — not a long list of text matches. Roam ranks candidate spans using lexical and available structural signals. Inspect the selected source and missing signals; ranking does not guarantee complete context.

Commands: roam context · roam retrieve · roam search-semantic · roam agent-context. 

$ roam retrieve "where does login validate sessions"
$ roam context UserService
$ roam agent-context --agent-id 1 --agents 3

3. "I'm about to edit X. What breaks?"

Before any edit, ask Roam for the blast radius: who calls this symbol transitively, which tests may be related, and what fitness rules guard the surrounding architecture. The answer tells you how widely the indexed relationships extend. Suggested tests still need execution; static relationships are not runtime coverage.

Commands: roam preflight · roam impact · roam affected-tests · roam diff · roam guard. 

$ roam preflight AuthService
$ roam impact AuthService
$ roam affected-tests AuthService

4. "Did the agent miss something on this PR?"

A patch can change one of several similar implementations or touch a function with callers elsewhere. Roam compares the intended patch with indexed relationships and saved clone evidence. Findings guide inspection; they are not automatically missed repairs.

Commands: roam critique · roam clones · roam pr-risk · roam pr-analyze. 

$ roam index
$ roam --json clones --persist
$ roam --json critique --working-tree --intent "Describe the intended change"

This selects tracked staged and unstaged changes against HEAD, not untracked files. Inspect the review source and each check's completion, scope, and freshness before relying on its verdict.

5. "Is the agent's patch correct but slow?"

Passing tests need not expose expensive behavior on larger inputs. Roam looks for supported patterns such as repeated lookups, database work inside loops, and repeated parsing. Inspect the matched source and assumptions, then measure a behavior-preserving alternative. A static finding is not proof of a bottleneck or a speedup.

Commands: roam math / roam algo · roam n1 · roam missing-index · roam hotspots. 

$ roam math
$ roam n1
$ roam hotspots --danger

6. "Is the architecture drifting?"

Layers blur. Cycles appear. Modules creep into each other. Roam reports topological layers, strongly-connected components, Louvain communities, Codebase Dark Matter (hidden co-change coupling), and a 0–100 health score with the worst-offending edges named. Wire the fitness rules into CI to fail PRs that introduce new cycles.

Commands: roam layers · roam clusters · roam health · roam dark-matter · roam spectral · roam fitness. 

$ roam health
$ roam layers
$ roam dark-matter
$ roam fitness

7. "Can I refactor safely?"

Model a supported move, extraction, or deletion in a copy of the graph before editing source. Inspect predicted structural changes and the proposed refactor plan. Simulation does not prove runtime behavior or build success; dynamic references need separate review. roam mutate is a separate source-editing workflow.

Commands: roam simulate · roam mutate · roam safe-delete · roam closure · roam plan-refactor. 

$ roam --json simulate move PaymentService src/billing/payment_service.py
$ roam safe-delete LegacyAdapter
$ roam plan-refactor PaymentService

8. "Multiple agents are working in parallel — can they?"

Hand three agents the same repo and they collide on the same files. Roam partitions the graph into low-coupling clusters, proposes bounded work partitions, and reports shared files, cross-partition dependencies, and a recommended merge order. A partition manifest does not enforce exclusive write access; review ownership conflicts before assigning agents. The CLI's automatic partition count is bounded to two through eight.

Commands: roam fleet · roam partition · roam orchestrate · roam agent-plan. 

$ roam partition --agents 3
$ roam orchestrate --agents 3
$ roam agent-plan --agents 3 --format claude-teams

9. "Which checks and evidence were recorded?"

Roam compiles change-time evidence into typed ChangeEvidence packets that answer the eight evidence questions (who acted, what authority, what context, what changed, what could break, what policy, what verified it, who accepted risk). Missing inputs remain gaps, and an actor label does not authenticate identity. Separate commands produce CodeGraph statements, command-specific SARIF, and OSCAL control mappings; not every exporter gathers from one shared packet. Roam maps to and supports evidence for controls; it never certifies or makes compliant. See /docs/agent-contract for the canonical envelope, /docs/architecture for the compiler, and /audit for the analyst-driven Roam Audit projection.

Commands: roam attest · roam cga · roam audit-trail-export · roam audit-trail-verify · --sarif. 

$ roam attest --format json --sign
$ roam audit-trail-export --since 2026-01-01
$ roam health --sarif > health.sarif

attest --sign adds a SHA-256 content hash, not a cosign signature. Use the separate cga signing and verification path when required. audit-trail-verify checks the PR-analysis trail; roam runs verify checks a run ledger. Neither establishes that all required tests ran.

What you don't ask Roam

Roam answers structural, graph-aware, and algorithmic-shape questions. It does not replace the tools that answer the rest. When the question is one of these, reach for the right tool — and check /compare for who does what.

  • Semantic correctness — does this function actually do what its name says, prose-level. Use an LLM reviewer (CodeRabbit, Greptile, Qodo) or a careful human.
  • Code style and formatting — line length, quote consistency, import order. Use a linter and formatter (Ruff, ESLint, Prettier, Black, gofmt).
  • Single-function security smells — string-concat SQL inside one function, hard-coded keys, unsafe deserialisation in isolation. Use a SAST tool (Semgrep, CodeQL, SonarQube). Roam complements these by showing whether the smell is reachable from an entry point (roam vulns, roam taint) — but the smell catalogue is theirs.
  • Type errors — use the type checker (mypy, tsc, pyright).
  • Runtime profiling — Roam predicts algorithmic shape from the graph. To measure a real run, use a profiler (py-spy, perf, your APM) and feed traces back via roam ingest-trace.

These tools answer different questions. Combining them can add useful evidence, but no fixed list establishes complete coverage. Keep the actual scope and remaining risks with the result.

Where to next

Read the agent contract · browse the full command reference · read the architecture · follow the setup guide.

See it run: The worked change-review demo — local queries, patch review, a saved bundle, and run-ledger verification.

Want help interpreting your project's history? Paid PR Replay reports cover an agreed PR scope and founder walk-through. The free local sample uses HEAD~5..HEAD, not five identified PRs.