roam-code

roam-code is a local codebase intelligence layer designed for AI coding agents. It provides local graph facts (symbols, calls, imports, git history, etc.) to help agents understand the impact of changes before they occur.

Key Characteristics

• Credential-free: No accounts, API keys, or cloud logins required.
• Local-first: Source parsing, indexing, and evidence generation stay on your machine. It does not upload source code or telemetry automatically.
• Tamper-evident ChangeEvidence: Generates signed, HMAC-chained packets that document who acted, what context was read, what changed, and what was verified.
• Dependency-aware: Uses a SQLite-backed graph of symbols across 28 languages rather than simple string matching (like grep).
• MCP Security: Every MCP response is scrubbed for secrets and gated against the active mode (read_only, safe_edit, migration, or autonomous_pr).

Roam provides small operational templates designed to shape day-to-day usage in repositories, issues, PR descriptions, or team runbooks. These are lighter alternatives to full audit or service reports and are intended to be copied directly into your workflow.

Available Templates

roam-code provides different ways to count how many callers a symbol has. Because each command answers a different question (e.g., counting every textual occurrence vs. counting unique upstream symbols), the numbers will vary.

Crucial for Consumers: When processing JSON output from roam commands, always check the caller_metric_definition string before comparing counts. This label identifies which of the four metrics was used.

The Four Metrics

Granularity (Finest to Coarsest): raw_edge_rows > distinct_caller_tuples > direct_in_degree > transitive_upstream_bfs.

To understand what context an agent read before making code changes (answering "did the agent look before it leapt?"), inspect the JSON files located in .roam/pr-bundles/<run_id>.json.

Key fields to examine:

• context_read.commands_run: Analysis commands executed (e.g., roam preflight, roam impact, roam describe).
• context_read.symbols_inspected: Symbols the agent analyzed.
• context_read.files_inspected: Files the agent inspected.

You can use jq or python -m json.tool to inspect these files.

{
  "intent": "Add idempotency key to /charge endpoint",
  "context_read": {
    "commands_run": [
      "roam preflight charge_handler",
      "roam impact charge_handler",
      "roam describe payment_gateway"
    ],
    "symbols_inspected": ["charge_handler", "PaymentGateway.charge", "IdempotencyStore"],
    "files_inspected": ["src/api/charge.py", "src/payments/gateway.py"]
  },
  "affected_symbols": [
    {"name": "charge_handler", "file": "src/api/charge.py", "blast_radius": 11}
  ]
}

A PR Replay report (generated by Roam Code v13.4+) follows a specific schema to answer the 'eight evidence questions' required for agentic assurance. The report sections map to these questions:

Important: If certain data (like Q3 context or Q8 human approvals) is not available from the upstream producer, the report will explicitly list these under Evidence limitations using the reason producer_not_available.

Roam Review is a planned hosted GitHub App designed for automated PR analysis. Its lifecycle is:

1. Trigger: A GitHub webhook (HMAC-SHA-256 signed) triggers the process on PR open/push.
2. Sandbox: An ephemeral, network-restricted sandbox container starts. The repository is cloned into this sandbox.
3. In-Memory Analysis: The command roam pr-analyze --json --rules .roam/rules.yml --audit-trail runs in-process and in-memory.
4. Feedback: A single sticky markdown comment is posted to the PR via the GitHub App installation token.
5. Destruction: The sandbox container and working copy are destroyed.
6. Retention: Only the verdict envelope (JSON metadata, no source bodies), an append-only audit-trail, and scrubbed operational logs are retained in an encrypted-at-rest store.

Failure Handling:

• Crashes: Containers are terminated immediately; no crash dumps or core files are persisted.
• Error Tracking: Stack traces sent to Sentry are stripped of source content (no function bodies, comments, or literals) and file paths are truncated to repo-relative.
• Timeouts: If analysis exceeds the wallclock budget (default 5 minutes), the sandbox is terminated and a timeout message is posted to the PR.

In Scope

• Replay of the current roam detector set against the agreed commit range.
• Aggregated detector-class breakdown of high-impact patterns.
• Per-PR ranking of findings by severity (high $\rightarrow$ medium).
• Recommended CI gates based on finding patterns.
• A live walk-through call and Markdown/PDF deliverables.
• Deep Tier Only: A written 90-day remediation plan with concrete roam commands and integration snippets.

Out of Scope

• Semantic correctness review: Checking if the code logic is correct (use tools like CodeRabbit, Greptile, or Qodo for this).
• Security audit: This is not a third-party penetration test; it surfaces structural risks (clones, layer violations) rather than exploit paths.
• Performance profiling: No benchmark runs are included.
• Pre-merge review: This covers merged history only. For in-flight PRs, use the free CLI or subscribe to Roam Review.