A worked example

Find the code. Check the change. Keep the record.

Follow one change from local repository questions to a saved review record. Your agent uses the findings to choose what to read and test. The record preserves the supplied evidence; it does not make missing checks pass.

Adapt this example to your project. Replace ensure_index and the intent text with the function and change you are investigating. These are terminal commands, not MCP calls. Run each step separately and inspect its result before continuing. Setup time and findings depend on the repository.

Step 1 — Build the local map

pip install "roam-code[mcp]"
cd /path/to/your/repo
roam init
roam --json doctor
roam --json health

Indexing records symbols and relationships in .roam/index.db by default. Doctor checks the installation and index; Health reports structural scores and findings, not whether the tests pass. Inspect their scope and incomplete-result disclosures.

Ordinary analysis needs no Roam account or analysis API key and does not automatically upload source. Package and parser downloads can use the network. Connected agents and explicitly selected online features have their own network paths.

Step 2 — Start the record before collecting checks

roam --json runs start --agent coding-agent

Keep the returned run ID. Bind subsequent commands to it with the ROAM_RUN_ID environment variable in the same terminal; this avoids relying on whichever in-progress run is newest. Replace the placeholder with the actual ID:

# PowerShell
$env:ROAM_RUN_ID = "<returned run ID>"

# Bash / zsh alternative
export ROAM_RUN_ID="<returned run ID>"

Use only the variant for your shell, then initialize the bundle:

roam mode safe_edit
roam --json pr-bundle init --intent "Harden ensure_index cold-start handling"

Check that bundle initialization succeeded before continuing. Full JSON responses from supported commands can be collected after initialization. Earlier responses, compact summaries, and commands that do not auto-log are not a complete run record.

Step 3 — Inspect the function and its surroundings

roam --json context ensure_index
roam --json preflight ensure_index
roam --json impact ensure_index

Read the returned source locations. Use indexed callers and related test candidates to decide what else needs attention. A large blast radius is a reason to investigate more carefully, not proof that those callers will break. A suggested test is not an executed test.

If resolution fails, the index is stale, or a required check is partial, keep that gap visible and resolve it before relying on a clean verdict.

Step 4 — Edit, refresh, and review the intended patch

Make the intended edit, run the project's required tests, and keep the actual results with their commands and source revision. Then refresh the index and saved clone evidence before reviewing the patch:

roam index
roam --json clones --persist
roam --json critique --working-tree --intent "Harden ensure_index cold-start handling"

--working-tree selects tracked staged and unstaged changes against HEAD; it does not include untracked files. Check summary.review_source and handle new files in the project's broader review process. An empty patch is not a completed review.

Critique checks saved clone evidence, indexed impact, and intent-related signals. Inspect each check's state and the clone scan's scope, caps, and freshness. It does not run every architecture policy or your tests. Run applicable rules, builds, and other required checks separately.

If a copied function appears in a finding, inspect whether the same change belongs there. Similar code does not automatically need an identical repair.

Step 5 — Inspect the saved bundle and verify the run

roam --json pr-bundle emit --strict

Read the emitted bundle path, collection results, and missing_proofs. Strict emission can refuse the bundle when required evidence, such as affected symbols or change verdicts, is absent. An executed test is not automatically a recorded bundle test. This example does not invent passing test records or promise a successful strict verdict.

Resolve missing evidence using the project's verification procedure and the installed roam pr-bundle --help. Do not switch off strict checks to get a green result. Keep a failed attempt and its reason even if you close the run.

Close the same run explicitly, using its ID from step 2 and a status that matches the outcome. For an incomplete or failed attempt:

roam --json runs end --run-id <returned run ID> --status failed
roam --json runs verify <returned run ID>

Replace both ID placeholders. Use --status completed only when the required work really completed, or --status abandoned when stopping the attempt. Closing with a status is an assertion; recorded failures can prevent a completed status. The environment binding alone does not select the run for runs end.

roam runs verify checks the run ledger's integrity. audit-trail-verify checks a different trail and is not a substitute. Integrity does not authenticate the actor, establish that every relevant check ran, or authorize publication.

What to keep

A saved preparation bundle is not automatically a cosign-signed CodeGraph attestation. Those are separate, explicitly configured formats and signing paths. Canonical serialization keeps a given packet stable; timestamps, builder versions, and supplied records can change later packets even on the same source.

Where to next