Without Roam

With Roam

Tool calls

8

1

Wall time

~11s

<0.5s

Tokens consumed

~15,000

~3,000

Verb

What it does

roam understand

Full codebase briefing: stack, architecture, key abstractions, health, conventions, entry points

roam context <symbol>

AI-optimized context: definition + callers + callees + files-to-read with line ranges

roam retrieve <task>

Graph-aware context for free-form tasks ("trace login flow", "where is the n+1?") — FTS5 + structural rerank within a token budget

roam preflight <symbol>

Pre-change safety gate: blast radius + tests + complexity + coupling + fitness

roam critique

Verify a patch against the graph: clones-not-edited + blast radius + intent vs semantic-diff. Pipe git diff in; exit 5 on high severity

Tool

Config file

Claude Code

CLAUDE.md in your project root

OpenAI Codex CLI

AGENTS.md in your project root

Gemini CLI

GEMINI.md in your project root

Cursor

.cursor/rules/roam.mdc (add alwaysApply: true frontmatter)

Windsurf

.windsurf/rules/roam.md (add trigger: always_on frontmatter)

GitHub Copilot

.github/copilot-instructions.md

Aider

CONVENTIONS.md

Continue.dev

config.yaml rules

Cline

.clinerules/ directory

Tool

Description

roam_adrs

Discover Architecture Decision Records (ADRs) and link them to code modules. Scans well-known ADR directories (docs/adr/ / architecture/decisions/ / ...) for markdown files matching ADR naming patterns, parses each ADR's title / status / date / file refs, then cross-references mentioned files against the symbol index. Different from roam_doc_staleness (inline docstring drift) -- this is the prose-decision-document discoverer.

roam_adversarial

Frame architectural issues in changed files as challenges the developer must defend: CRITICAL (new cyclic dependencies), HIGH (layer violations, high-confidence anti-patterns), WARNING (cross-cluster coupling, high fan-out), INFO (orphaned symbols). Composes cycles + clusters + layers + catalog + dead + complexity. Different from roam_diff (blast-radius facts) -- this is the architecture-review framing for code-review agents.

roam_adversarial_review

Adversarial architecture review: challenges about cycles, anti-patterns, coupling.

roam_affected

Monorepo impact analysis: find all affected packages/modules from changes.

roam_affected_tests

List the tests you actually need to run after editing a symbol or file. Use when user asks 'which tests do I run?', 'what tests cover X?', or after Edit/Write. Walks reverse-dependencies with hop distance — closer hops run first. For a full pre-commit check (blast radius + fitness + tests), use roam_prepare_change.

roam_agent_context

Extract a single agent's partition from the full agent plan: write scope, read-only dependencies, interface contracts, coordination instructions, and key symbols. Different from roam_agent_plan (full multi-agent view) and roam_orchestrate (operational dispatch with merge order) -- this is the focused per-worker packet for one agent.

roam_agent_export

Generate AI agent context file (CLAUDE.md/AGENTS.md/.cursorrules) from index.

roam_agent_plan

Decompose partitions into dependency-ordered multi-agent tasks: per-task write scope, read-only dependencies, interface contracts, phase schedule, and merge sequencing. Supports plain / json / claude-teams output formats. Different from roam_partition (raw analytical manifest) and roam_orchestrate (operational dispatch) -- this is the dependency-ordered phase schedule.

roam_agent_score

Aggregate runs from the local ledger and score each agent on a 0..100 composite (run completion, gate adherence, preflight compliance, blast accuracy, replay survival). Empty state (no runs / no matching runs) returns a clean envelope with state: "no_data" -- never empty stdout, never a crash. Different from roam_runs_verify (HMAC tamper-detection) -- this is the per-agent quality score across runs.

roam_ai_ratio

Estimate AI-generated code percentage from git commit heuristics.

roam_ai_readiness

AI readiness score (0-100): how effectively AI agents can work on this codebase.

roam_alerts

Active health alerts: thresholds breached on tangle, complexity, churn, or coverage.

roam_algo

Detect suboptimal algorithms with better alternatives and complexity analysis.

roam_annotate_symbol

Add persistent annotation to a symbol/file for future agent sessions.

roam_api

List the public API surface — exported public symbols with signatures and docs.

roam_api_changes

Detect breaking and non-breaking API changes vs a git ref.

roam_api_drift

Mismatches between backend models and frontend interfaces.

roam_architecture_drift

Compute per-week growth rates for symbols / edges / cycles across a sliding window of persisted .roam/snapshots/ and classify overall direction as improving / degrading / stable. Different from roam_graph_diff (point-in-time delta between two commits) and roam_trends (metric-level time series) -- this is the snapshot-based architectural-trajectory report.

roam_article_12_check

Run a 6-item EU AI Act Article 12 readiness checklist over the indexed repo: audit-trail directory, audit-trail records, retention policy doc, technical docs, attestation surface, high-risk classification heuristic. Emits a structured envelope mapping each item to its Article (12, 18, 19) or Annex (III). Different from roam_audit_trail_conformance_check (per-record chain integrity) -- this is the repo-level governance-readiness assessment. Per the agentic-assurance guardrails: 'maps to' / 'supports evidence for', never 'certifies' / 'makes compliant'.

roam_ask

Route a natural-language codebase question to the right roam recipe. Use when user asks 'is it safe to delete X?', 'where does login validate?', 'what just broke?', 'who owns module Y?', 'trace the n+1 in checkout'. Maps intent to one of 25 composed recipes (onboard / trace-task / find-bug / verify-patch / explore-impact / security-audit / who-owns / what-changed / explore-tests / dependency-update / ...). Try this BEFORE falling back to Grep+Read — the dispatcher covers most workflows in one tool call. Even low-confidence results contain signal.

roam_attest

Proof-carrying PR attestation: evidence bundle + merge verdict.

roam_audit

Run a one-shot codebase architecture audit: bundles health, debt, dead-code, risk, test-pyramid, coverage, and API-surface signals into a single envelope. Designed as the structured artifact a written audit report attaches. Different from roam_health (single 0-100 score) and roam_report (preset-driven Markdown report) -- this is the verdict-first audit packet for governance and onboarding.

roam_audit_trail_conformance_check

Score the audit trail against an EU AI Act Article 12 checklist.

roam_audit_trail_export

Export the audit trail as markdown / json / csv for procurement review.

roam_audit_trail_verify

Verify SHA-256 chain integrity of a roam audit trail.

roam_auth_gaps

Endpoints missing authentication or authorization checks.

roam_batch_get

Get details for up to 50 symbols in one call. Replaces 50 sequential roam_symbol calls.

roam_batch_search

Search up to 10 patterns in one call. Replaces 10 sequential roam_search_symbol calls.

roam_bisect_blame

Find snapshots that caused architectural degradation, ranked by impact.

roam_boundary

Surface public-by-accident exports + changed-range layer violations. Two closed-enum kinds: public_by_accident (warning, _-prefixed name in all) and wrong_direction_import (high, lower-layer module imports from higher-layer caller).

roam_breaking_changes

Detect breaking API changes between git refs: removed exports, changed signatures.

roam_brief

Compose a one-page agent briefing covering five sections: next (what roam next would recommend), highlights (stack / top danger zones / top mined laws from roam agents-md), pr_bundle (current PR-bundle status on the active branch), mode (active agent mode and its allow-list size), and runs (the N most-recent runs from the ledger). Designed as the FIRST command an agent runs when joining a roam-indexed repo. Different from roam_next (single-command router) -- this is the verdict-first session kickoff packet.

roam_budget_check

Check changes against architectural budgets (cycles, health floor, complexity).

roam_bus_factor

Score knowledge-concentration risk per directory: Shannon entropy over unique authors, primary-author share, last activity, and a staleness factor. Flags CRITICAL / HIGH / MEDIUM / LOW per module. Different from roam_owner (per-file blame) and roam_congestion (too-many-authors merge-conflict risk) -- this measures knowledge-loss risk.

roam_capsule_export

Sanitized structural graph export without code bodies (privacy-safe).

roam_catalog

Return the full machine-readable list of every roam MCP tool currently registered, including title, description, and capability flags (core / read_only / destructive). Use this once at session start to discover what's available without enumerating tools.

roam_causal_graph

Build per-symbol causal graphs: edges from inputs (parameters / globals / env reads) to sinks (side-effecting calls / return / raise / mutation). Six causal kinds: param_to_effect, param_to_return, global_to_effect, global_to_mutation, env_to_effect, param_to_raise. Heuristic line-level text scan -- false negatives expected. Different from roam_taint (cross-symbol taint propagation) -- this is intra-symbol dataflow only.

roam_cga_emit

Emit a Code Graph Attestation — in-toto v1 statement with predicate type https://roam-code.com/spec/CodeGraph/v1 (or https://roam-code.com/spec/CodeGraph-AIBOM/v1 with --aibom). Merkle root over symbol fingerprints + edge-bundle digest. Optional cosign keyless or offline signing.

roam_cga_verify

Verify a Code Graph Attestation — re-derives the Merkle root + edge-bundle digest from the live DB and compares to the bundled predicate, AND verifies the cosign signature on the sibling .bundle. Fails closed (exit 5) when no bundle is present unless no_cosign=True is passed to acknowledge predicate-only verification.

roam_changelog

List commits since last tag, optionally formatted as a markdown CHANGELOG draft.

roam_check_rules

Run 10 built-in structural rules: cycles, fan-out, complexity, tests, god classes, layer violations.

roam_clean

Remove orphaned index entries (files deleted from disk) without full rebuild.

roam_clones

Detect near-duplicate code via AST structural hashing (Type-2 clones).

roam_closure

Minimal set of changes needed for rename/delete/modify (exact files + lines).

roam_clusters

Show Louvain code clusters and directory mismatches. Returns per-cluster size, cohesion, conductance, modularity Q, mega-cluster sub-group breakdowns, and inter-cluster coupling. Different from roam_layers (dependency-layer violations) -- this groups by community detection, not by topological depth.

roam_codeowners

CODEOWNERS coverage, ownership distribution, unowned files, drift detection.

roam_compare

Diff two roam indices structurally: reports symbols added/removed/moved, per-file complexity deltas above a threshold, language counts, and a one-line health verdict (improved / regressed / sideways). Different from roam_graph_diff (commit-range graph delta from one index) -- this is the cross-index structural delta for release-vs-release comparisons.

roam_compatibility

Detect outbound surface regressions vs a baseline snapshot. Closed-enum verdicts: no regressions / surface additions / surface drift / breaking changes. Compares commands, flags, envelope summary fields, MCP tools, and preset counts. Capture the baseline via CLI: roam compatibility --write-baseline PATH.

roam_complete

Prefix completion for symbols / file paths / commands. Faster than search; returns just names.

roam_complexity_report

Functions ranked by cognitive complexity above threshold.

roam_congestion

Detect developer congestion: files with too many concurrent authors within a sliding time window. Combines author count, churn intensity, and complexity into a congestion score that predicts merge conflicts and coordination failures. Different from roam_bus_factor (knowledge-loss risk) and roam_owner (per-file blame breakdown) -- this measures too-many-cooks contention.

roam_context

Get the minimum files + line ranges needed to understand or modify a symbol. Use when user says 'show me X', 'I need to change Y', 'how does Z work?'. Returns targeted reads ranked by PageRank — cheaper than Read'ing whole files. For pre-change safety (blast radius + tests + effects), use roam_prepare_change instead.

roam_conventions

Auto-detect codebase naming, file, import, and export conventions with outliers.

roam_coupling

Show temporal coupling: file pairs that change together. Reads git history to find files with high co-change frequency. Different from roam_fan (structural connectivity) and roam_dark_matter (hidden co-change) -- this measures file-level temporal coupling.

roam_coverage_gaps

Find unprotected entry points: top-level exported functions / methods that have no call-graph path to a required gate symbol (auth / permission / validation). Supports exact gate names, regex patterns, framework presets (python / javascript / go / java-maven / rust), and a .roam-gates.yml sidecar config. Different from roam_auth_gaps (PHP/Laravel source analysis) and roam_test_gaps (untested symbols in changed files) -- this walks the call graph to verify every entry reaches a required gate.

roam_critique

Verify a unified diff against the codebase graph BEFORE merge. Use when user asks 'review my patch', 'is this PR safe?', or after generating any non-trivial diff. Catches clones-not-edited (missed duplicates the agent should have updated together) + blast-radius hop count. Pass git diff output as diff_text. Grounded against the indexed graph, not vibes.

roam_cut

Find fragile domain boundaries via minimum-cut analysis. Computes the thinnest edge cuts between architectural clusters and the highest-impact 'leak edges' whose removal would best improve domain isolation. Different from roam_split (decomposes a single file) -- this finds boundaries between clusters.

roam_cut_analysis

Minimum cut analysis: fragile domain boundaries, highest-impact leak edges.

roam_dark_matter

File pairs that co-change without structural links (hidden coupling).

roam_dashboard

Unified single-screen codebase status: health, hotspots, bus factor, dead code, AI rot.

roam_dead_code

Unreferenced exported symbols (dead code candidates).

roam_debt

Prioritized tech debt with SQALE remediation cost estimates.

roam_delete_check

Gate the diff (working / staged / PR / HEAD) on surviving references to deleted symbols and files. Per-deletion verdict: SAFE (no surviving references), LIKELY-SAFE (survivors only in tests / docs / unreachable code), or BREAK-RISK (survivors in reachable code). Different from roam_critique (PR-wide diff review) -- this targets the deletion surface specifically with CI-gate semantics (overall BREAK-RISK trips the gate).

roam_deps

File-level imports and importers (what depends on this file).

roam_describe

Auto-generate a project description for AI coding agents: multi-section Markdown report covering overview, directories, entry points, key abstractions, architecture, and testing. Different from roam_understand (compact codebase overview) -- this is the comprehensive prose description for CLAUDE.md / AGENTS.md / .cursor/rules. The wrapper emits to stdout; on-disk writes are deferred to the CLI (roam describe --write) so the MCP surface stays read-only.

roam_dev_profile

Developer behavioral profiling: commit time patterns, change scatter (Gini), burst detection.

roam_diagnose

Root cause analysis: upstream/downstream suspects ranked by composite risk.

roam_diagnose_issue

Find root-cause suspects for a failing symbol. Use when user reports 'X is broken', 'test Y fails', 'why does Z return null?', 'this exception traces to ...'. Ranks upstream / downstream callers by composite risk and lists side effects + transactional boundaries. Replaces manual Grep+Read traversal of the call graph. Pass the suspect symbol.

roam_diff

Show the blast radius of your edits BEFORE you commit. Run after Edit/Write tools to see affected symbols, files, tests, plus coupling and fitness warnings. Use when user asks 'what did my change break?', 'safe to commit?'. Replaces ad-hoc git diff --stat inspection with graph-aware impact data. For PR-level risk verdict, use roam_pr_risk.

roam_disambiguate

List every symbol matching a name with file/line/kind/signature/PageRank — pick the right overload.

roam_doc_intent

Link documentation to code: find drift, dead refs, undocumented symbols.

roam_doc_staleness

Detect stale docstrings: docs whose body has drifted since the comment was written. Uses git blame to compare docstring timestamps against code body timestamps. Different from roam_docs_coverage (missing docs ranked by PageRank) and roam_stale_refs (dangling doc links) -- this audits what existing docs SAY.

roam_docs_coverage

Doc coverage + stale-doc drift with PageRank-ranked missing docs.

roam_doctor

Setup diagnostics: Python version, tree-sitter, git, index existence, freshness, SQLite.

roam_dogfood

One-shot full-stack run: audit + pr-analyze + audit-trail + conformance.

roam_dogfood_aggregate

Triage view over the dogfood eval corpus: totals, per-command findings count, by-status / by-severity / by-type breakdowns. Reads internal/dogfood/evals/ (or an override path). Useful for agents auditing roam-code itself; mostly a no-op on consumer repos that have no dogfood corpus.

roam_drift

Ownership drift detection: declared CODEOWNERS vs actual time-decayed contributors.

roam_duplicates

Detect semantically duplicate functions via structural similarity.

roam_effects

Side effects of functions: DB writes, network, filesystem (direct + transitive).

roam_endpoints

List all REST/GraphQL/gRPC endpoints with handlers, methods, and locations.

roam_entry_points

Catalog every entry point into the codebase: HTTP routes, CLI commands, scheduled jobs, event handlers, message consumers, main functions, and exports. Reports per-entry reachability coverage -- what fraction of symbols each entry transitively reaches through the call graph.

roam_eval_retrieve

Run the retrieval eval harness over a labeled task set. Reports recall@K, mean reciprocal rank, and per-task diagnostics. Supports a weight sweep and CodeRAG-Bench / BEIR emit formats for public leaderboard submission.

roam_evidence_diff

Diff two ChangeEvidence packets: shows hash drift, schema drift, added/removed refs, missing evidence, and changed verdicts. Useful for reviewing PR re-runs, comparing replay windows, or auditing whether a fresh evidence packet has improved or regressed against a stored baseline. Different from roam_compare (two-index structural delta) -- this is the two-packet evidence delta.

roam_evidence_doctor

Diagnose a ChangeEvidence packet's health: schema validity, closed-enum conformance, content_hash integrity, completeness banner tier (STRONG / PARTIAL / INSUFFICIENT), declared redactions, and actionable next steps for partial / missing evidence questions. Read-only.

roam_evidence_oscal

Emit an OSCAL v1.2 document. Default kind='control-mapping' compiles the roam control map (maps roam evidence to EU AI Act, ISO/IEC 42001, NIST AI RMF, NIST AI 600-1, NIST SP 800-218A, SOC 2, internal AI-change policy). kind='assessment-results' compiles a per-run AR document from a ChangeEvidence packet (requires evidence_path); AR mandates an Assessment Plan reference — pass import_ap_ref for an external AP or omit it to inline a synthesized stub AP. Supports evidence for the listed frameworks — does not certify compliance. Two roam-specific concepts (authority_refs, redactions) surface as OSCAL prop extensions under the urn:roam:oscal:v1 namespace.

roam_expand_toolset

List available tool presets or show contents of a preset. Presets: core (57), review (70), refactor (70), debug (69), architecture (71), compliance (13), full (227).

roam_explore

Codebase exploration bundle: understand overview + optional symbol deep-dive in one call.

roam_fan

Show fan-in / fan-out: the most-connected symbols or files. Flags hub / spreader / HIGH-RISK structural hotspots based on cross-file import / call edges. Different from coupling (co-change frequency) -- this measures structural connectivity.

roam_fetch_handle

Fetch all or part of a large payload by handle — supports byte slice, section pick, jq projection.

roam_file_info

File skeleton: all symbols with signatures, kinds, line ranges.

roam_findings_count

Show per-detector finding counts. Useful for spotting which detectors have migrated to the central registry vs which are still only emitting to their detector-specific tables.

roam_findings_list

List rows from the central findings registry, optionally filtered by detector or subject. Cross-detector view -- every migrated detector (clones, dead, complexity, smells, n1, missing-index, ...) emits here behind one schema.

roam_findings_show

Show full detail for a single finding by its stable finding_id_str. Returns the detector version, subject, confidence tier, claim, evidence JSON, and any suppressions.

roam_fingerprint

Topology fingerprint for cross-repo comparison or structural drift tracking.

roam_fitness

Run architectural fitness functions from .roam/fitness.yaml: dependency constraints, layer enforcement, metric thresholds, naming conventions, and trend regression guards. Different from roam_preflight (compound 6-signal pre-edit gate) -- this is the dedicated fitness surface with per-rule output, baseline / delta mode, and trend regression guards.

roam_flag_dead

Detect potentially stale feature-flag code: flags referenced only once, flags always checked with the same boolean default, and flags clustered in a single file. Recognises LaunchDarkly, Unleash, Split, generic feature_flag(...) calls, and FEATURE_* env-var patterns. Different from roam_dead_code (graph-unreachable symbols) -- this targets code that is alive in the graph but gated behind flags that may never fire.

roam_fleet_plan

Plan a multi-agent fleet for a goal — graph-aware partition (Louvain + co-change) emits .roam-fleet.json for Composio / Copilot CLI / raw.

roam_fn_coupling

Show function-level temporal coupling: symbol pairs that change together across commits. Different from roam_coupling (file-level pairs) -- this drills into co-changing symbols inside and across files, with optional structural-edge filtering.

roam_for_bug_fix

Compound: diagnose + affected_tests + diff + context for a symbol you're about to debug.

roam_for_new_feature

Compound: understand + search + context + complexity for an area you're about to add code to.

roam_for_refactor

Compound: preflight + impact + complexity_report + clones for a symbol you're about to refactor.

roam_for_security_review

Compound: taint + vuln + critique + adversarial for a security review pass.

roam_forecast

Predict when metrics will exceed thresholds (Theil-Sen regression).

roam_generate_plan

Structured execution plan for code modification: read order, invariants, tests.

roam_get_annotations

Read annotations for symbols, files, or project. Filter by tag/date.

roam_get_invariants

Implicit contracts for symbols: signature stability, usage spread, breaking risk.

roam_graph_diff

Show the structural graph delta between two snapshots. Surfaces new / removed symbols, edge churn, degree shifts, new cycles, layer migrations, and likely renames. Reads persisted snapshots from .roam/snapshots/ -- capture one with --save-snapshot.

roam_graph_stats

Report graph-level invariants: density, connected components, average in/out degree, top in-degree symbols, and approximate diameter. One overview number for 'how dense, connected, and cyclic is this codebase'.

roam_grep

Run index-aware grep across the codebase. Returns matches with their enclosing symbol, reachability badge, PageRank, clone-class, and bridge annotations. Supports multi-pattern, source-only / test-only filters, reachable-from / unreachable filters, co-occurrence across patterns, and rank-by importance.

roam_guard

Check breaking-change risk for a symbol before editing: 0..100 risk score with component breakdown (blast radius, complexity, centrality, test gap, layer analysis) plus caller / callee lists and covering tests -- all within a ~2K-token budget. Different from roam_preflight (file / staged / coupling / convention / fitness composite) -- this is the per-symbol quantified risk score for sub-agent dispatch.

roam_health

Codebase health score (0-100) with issue breakdown, cycles, bottlenecks.

roam_history_grep

Run git pickaxe (-S / -G) through commit history. Returns commits that introduced or removed the literal string, with author, date, short SHA, and summary per commit.

roam_hotspots

Show runtime hotspots: symbols ranked by static analysis vs real production traces (requires roam ingest-trace to have populated runtime_stats). Each row is tagged UPGRADE (runtime-critical but statically safe), CONFIRMED (both agree), or DOWNGRADE (statically risky but low traffic). Different from roam_why_slow (top-N by latency alone) -- this classifies static vs runtime mismatch.

roam_hover

One-line architectural summary for a symbol — kind, location, blast-radius bucket, top caller, top callee.

roam_idempotency

Classify symbols by retry safety: idempotent (pure, read-only I/O, write-with-check patterns like mkdir(exist_ok=True) / INSERT OR IGNORE / UPSERT / if not exists: create), non_idempotent (naive writes, mutations, appends), or unknown (process spawn / unreadable body). Composes on top of roam_side_effects. Different from roam_tx_boundaries (transaction correctness) -- this answers is it safe to retry?.

roam_impact

Blast radius for 'is it safe to change?' — symbols + files affected, in 5 lines. Compact decision-support output. Round 4 / S: the right default tool for safety-checks; preflight is heavier.

roam_ingest_trace

Ingest runtime traces (OTel/Jaeger/Zipkin), match spans to symbols.

roam_init

Initialize roam and build the first index. Task-mode for non-blocking setup.

roam_intent

Link documentation to code: find which docs mention which symbols, and detect doc-to-code drift (references to non-existent symbols). Different from roam_docs_coverage (PageRank-ranked missing-docstring hotlist) and roam_doc_staleness (stale docstring content) -- this is the prose-doc-to-symbol linker plus drift detector.

roam_invariants

Discover implicit contracts for a symbol or the public API surface: signature shape, parameter count and ordering, usage spread across files, dependency set. Different from roam_check_rules (explicit governance rules) -- this is the AUTO-discovered implicit-contract surface so agents know what must stay stable when modifying a symbol.

roam_layers

Show topological dependency layers and violations. Returns each layer's symbol count, directory breakdown, and any back-edges that violate the topological order. Different from roam_clusters (community detection) -- this measures dependency depth.

roam_llm_smells

Run LLM-API integration linter over indexed files: detects unpinned model versions, missing max_tokens, prompt injection via user-input concatenation, unvalidated json.loads on LLM output, and missing temperature. Different from roam_vibe_check (AI-generated code shape) and roam_smells (structural anti-patterns) -- this is the production gate for human-authored LLM-using code.

roam_map

Show project skeleton: directory tree, entry points, top symbols by PageRank, language counts. Different from roam_describe (prose description) and roam_minimap (sentinel-block one-pager for CLAUDE.md) -- this is the structured skeleton with directories, entry points, and ranked symbols for agent onboarding.

roam_metrics

Show unified per-file or per-symbol metrics: cognitive complexity, fan-in / fan-out, SNA centrality vector (PageRank / betweenness / closeness / eigenvector / clustering coefficient), composite debt score, churn, test coverage, and comprehension difficulty in a single view.

roam_metrics_push

Push metrics-only summary to Roam Cloud Lite. Default is dry-run.

roam_migration_plan

Generate an ordered migration plan with risk + blast-radius per step from a target-architecture YAML spec or inline --move SYMBOL=path/to/new/file directives. Each step is annotated with caller count and a derived risk score so agents can decide where to stop or insert tests. Stops at the first step exceeding max_risk. Different from roam_simulate (counterfactual single-move analysis) -- this is the ordered multi-step plan with a risk gate.

roam_migration_safety

Non-idempotent database migrations (unsafe for re-run).

roam_minimap

Generate a compact ~20-line codebase minimap for CLAUDE.md injection: tech stack, annotated directory tree, key symbols by PageRank, high-fan-in symbols to avoid, hotspots, detected conventions. Different from roam_describe (long-form prose) and roam_map (structured skeleton) -- this is the sentinel-block one-pager. The wrapper emits to stdout; on-disk updates are deferred to the CLI (roam minimap --update / --init-notes) so the MCP surface stays read-only.

roam_missing_index

Queries on non-indexed columns (slow query risk).

roam_module

Show directory contents: exported symbols, signatures, external imports / importers, internal cohesion percentage, and API surface ratio. Different from roam_describe (project-wide) -- this analyses a single directory.

roam_mutate

Agentic editing: move/rename/add-call/extract symbols with auto-import rewrite.

roam_n1

Detect N+1 I/O patterns in ORM code (Laravel/Django/Rails/SQLAlchemy/JPA).

roam_next

Suggest the next roam command based on cheap repo-state signals: index presence, staleness, working-tree dirtiness, recent envelope, and recent memory. Emits one imperative recommendation in <200ms. Different from roam_brief (multi-section session kickoff) and roam_workflow (curated multi-step recipes) -- this is the single-command router.

roam_onboard

Generate a new-developer onboarding guide for the codebase.

roam_oracle_batch

Run multiple oracle queries in one call. Items: [{name, oracle, max_hops?}, ...] where oracle is one of symbol-exists, route-exists, is-test-only, is-reachable-from-entry, is-clone-of.

roam_oracle_is_clone_of

Answer the boolean oracle question: does this symbol have persisted clone siblings in the clone_pairs table? Returns a yes/no verdict envelope with the matched clone class size. Different from roam_clones (full clone-pair enumeration) -- this is the cheap boolean lookup for one symbol's clone status.

roam_oracle_is_reachable_from_entry

Answer the boolean oracle question: is the symbol reachable from any entry point via the call graph (BFS up to max_hops depth)? Useful for sniffing orphans and production-vs-tooling code. Different from roam_dead_code (broad dead-symbol detection) and roam_entry_points (entry-point enumeration) -- this is the cheap boolean lookup for one symbol's reachability.

roam_oracle_is_test_only

Answer the boolean oracle question: are ALL callers of this symbol in test files? Useful for sniffing test fixtures and dead-but-test-only helpers. Different from roam_dead_code (broad dead-symbol detection) -- this is the cheap boolean lookup for one symbol's test-only status.

roam_oracle_route_exists

Answer the boolean oracle question: does a route handler match this URL path? Returns a yes/no verdict envelope with the matched handler's file + kind when found. Different from roam_endpoints (full endpoint enumeration) -- this is the cheap boolean lookup for one route precondition check.

roam_oracle_symbol_exists

Answer the boolean oracle question: does a symbol with this name exist in the index? Returns a yes/no verdict envelope with the matched symbol's file + kind when found. Different from roam_search_symbol (top-N ranked hits) -- this is the cheap boolean lookup for agent precondition checks.

roam_oracle_test_only

Alias of roam_oracle_is_test_only — preserves the shorter name agents sometimes guess.

roam_orchestrate

Partition codebase for parallel multi-agent work with exclusive write zones.

roam_orphan_imports

List imports that don't resolve to any indexed module or installed package -- catches typo'd local imports, missing packages, and dangling relative imports. Covers Python (default), JavaScript / TypeScript, and Go. Different from roam_dead_code (unused symbols) -- this targets import-statement orphans.

roam_orphan_routes

Backend routes with no frontend consumer (dead endpoints).

roam_over_fetch

Models serializing too many fields (data over-exposure risk).

roam_owner

Show code ownership computed from git blame: per-author line counts, percentages, last-active dates, and a fragmentation index. Works on a file or a directory prefix. Different from roam_codeowners (which reads the CODEOWNERS file) -- this measures actual ownership.

roam_partition

Multi-agent work partitioning: split codebase into independent work zones.

roam_path_coverage

Critical call paths with zero test protection, ranked by risk.

roam_patterns

Detect positive architectural patterns: Singleton, Factory, Observer, Repository, Middleware, Strategy, and Decorator. Different from roam_smells (negative anti-patterns) -- this discovers intentional design patterns.

roam_plan

Generate a structured execution plan for modifying code: read-order (call-graph BFS), invariants (mined contracts), blast-radius preview, and per-task heuristics. Five task types: refactor / debug / extend / review / understand. Different from roam_plan_refactor (refactoring-specific simulation) and roam_preflight (blast-radius gate) -- this is the general-purpose work plan for any task type.

roam_plan_refactor

Build an ordered refactor plan for one symbol using risk/test/simulation context.

roam_postmortem

Replay current detectors against past commits: walks a git commit range, runs roam critique against each commit's diff, and reports which findings would have surfaced pre-merge. Useful for retrospective replay -- 'would today's detector set have caught the incidents already in history?' Different from roam_pr_replay (one PR replay) -- this is the range-replay over historical commits.

roam_pr_analyze

Agent-aware PR risk verdict — INTENTIONAL / SAFE / REVIEW / BLOCK.

roam_pr_comment_render

Render a markdown PR comment from a pr-analyze JSON envelope.

roam_pr_diff

Structural graph delta of code changes: metric deltas, layer violations.

roam_pr_prep

One-shot pre-PR fitness check: bundles diff blast radius + critique + pr-risk into a single envelope with a ready_to_open verdict. Different from roam_pr_risk (composite risk score alone) and roam_critique (clones-not-edited + blast-radius alone) -- this is the three-section pre-PR rollup with the go/no-go verdict.

roam_pr_risk

Risk score (0-100) for pending changes with per-file breakdown.

roam_preflight

Pre-change safety check: blast radius, tests, complexity, fitness. Call BEFORE modifying code.

roam_prepare_change

Bundle everything needed before editing a symbol: blast radius, affected tests, files to read, side effects, fitness gates. Call BEFORE Edit/Write on non-trivial code. Use when user asks 'is it safe to change X?', 'what do I need to know to refactor Y?', 'show me what depends on Z'. Replaces manual preflight + context + effects sequence.

roam_py_modern

Python modernisation signal: walrus, match, PEP 604/585, f-strings vs legacy.

roam_py_types

Python type-annotation health: % public fns fully typed, Any usage, legacy typing.

roam_pytest_fixtures

pytest fixture chain: top fixtures by dependent count, or per-symbol dependency walk.

roam_recommend

Surface symbols related to a given symbol via three signal sources combined: call-graph neighbours (1-hop in + out), git co-change (other symbols whose files changed in the same commits), and persisted clone siblings (when roam clones --persist was run). Each candidate gets a score that's the normalised sum of the three contributions. Different from roam_impact (transitive blast radius) and roam_neighbours (graph-only 1-hop neighbours) -- this fuses co-change + clones into the ranking.

roam_refs_text

Audit literal strings across the project and emit a per-string verdict: SAFE-TO-REMOVE / REVIEW / LOAD-BEARING. Groups every reference by surface (code, test, docs, config, generated, vendored) and annotates reachability for code hits.

roam_reindex

Incremental or force reindex. Task-mode + elicited confirmation for force runs.

roam_relate

How symbols connect: shared deps, call chains, conflicts, cohesion score.

roam_repo_map

Compact project skeleton with key symbols per file, by PageRank.

roam_report

Run a compound report preset (built-ins: first-contact, security, pre-pr, refactor, guardian) that orchestrates multiple analysis commands into one rendered report. Different from roam_audit (single fixed bundle) -- this is the preset-driven multi-command roll-up with optional Markdown output and strict exit-code gating.

roam_reset

Delete index DB and rebuild from scratch. Requires force=True. Recovery for corrupted indexes.

roam_retrieve

Graph-aware context for free-form tasks: FTS5 + structural rerank (PageRank + clones) + token budget.

roam_review_change

Change review bundle: pr-risk + breaking changes + structural diff in one call.

roam_risk

Rank symbols by domain-weighted risk: combines static risk (fan-in + fan-out + betweenness) with domain criticality weights so financial / auth / data-integrity symbols rank higher than UI symbols. Different from roam_fan (raw fan-in/out degree) and roam_hotspots (runtime hotspot classification) -- this is the semantic-domain-weighted risk heatmap.

roam_rules_check

Evaluate custom governance rules from .roam/rules/ YAML files.

roam_rules_validate

Lint a .roam/rules.yml for shippability before customers see it.

roam_runtime_hotspots

Runtime hotspots where static and runtime rankings disagree (UPGRADE/DOWNGRADE).

roam_safe_delete

Fuse dead-code, blast-radius, and test-coverage signals into a single deletion verdict: SAFE / REVIEW / UNSAFE. Reports direct callers (non-test), transitive dependents, affected files, and a public-API bump that flips SAFE -> REVIEW for exported symbols whose name matches a common public-API prefix. Different from roam_dead_code (all unreferenced symbols) and roam_impact (transitive blast radius) -- this is the single go/no-go gate.

roam_safe_zones

Classify the refactor containment zone around a symbol or file: ISOLATED (no external connections), CONTAINED (<=5 boundary symbols), or EXPOSED (>5). Reports strictly-internal vs boundary symbols and external caller / callee counts per boundary. Different from roam_impact (unbounded reverse blast radius) and roam_closure (exact locations needing modification) -- this maps the bounded zone where it is safe to refactor freely.

roam_sbom

Emit a Software Bill of Materials (CycloneDX 1.7 by default, or SPDX 2.3) enriched with call-graph reachability — distinguishes phantom dependencies from those actually exercised. Pair with --aibom for the AIBOM extension required by EU AI Act Art. 50.

roam_search_semantic

Find symbols by natural language query (hybrid BM25 + vector + framework packs).

roam_search_symbol

Look up a function / class / method by partial name. Use when user mentions a symbol ('the login handler', 'AuthService.refresh', 'handleSave') and you need the file path, line, kind, and qualified name. Replaces Bash: grep -n 'def name' src/ + Read. Returns PageRank-ranked results — most-important match first. Do NOT use for finding references — that's roam_uses. For 3+ patterns at once use roam_batch_search.

roam_secrets

Scan for hardcoded secrets, API keys, tokens, passwords (24 patterns).

roam_semantic_diff

Structural change summary: what symbols were added/removed/modified.

roam_session_metrics

Local-only telemetry: per-tool invocation counts grouped by outcome (success / rate_limited / error). Helps answer "which tools are agents actually using?" and "are 90 of the 227 tools dead weight?". Never phones home — counters live in the MCP server process and reset on restart.

roam_side_effects

Classify symbols by side-effect bucket: none (pure), io_read (disk / network / DB read), io_write (disk / network / DB write), mutation (global / module state mutation), process (subprocess / thread / async), or unknown. Coarse five-bucket taxonomy designed for agent decisions. Different from roam_effects (finer 11-kind taxonomy + transitive propagation) -- this is the agent's go/no-go classifier for can I retry this safely?.

roam_simulate

Predict metric deltas from move/extract/merge/delete operations.

roam_simulate_departure

Simulate knowledge loss if a developer leaves the team.

roam_sketch

Render a compact structural skeleton of a directory: every file's exported symbols with kind, signature, line range, and first-line docstring. Different from roam_understand (broader project overview) and roam_file_info (one-file skeleton) -- this is the directory-level API surface in a single view, with optional full=True to include private symbols.

roam_smells

Run 24 deterministic code-smell detectors over the indexed codebase: brain methods, god classes, deep nesting, shotgun surgery, feature envy, long parameter lists, large classes, dead params, low cohesion, message chains, data clumps, type switches, cross-layer clones, parallel hierarchies, and more. Different from roam_vibe_check (AI-rot pattern regex) and roam_patterns (positive design patterns) -- this surfaces negative structural anti-patterns from DB queries.

roam_spectral

Spectral bisection: Fiedler vector partition tree and modularity gap.

roam_split

Analyse a file's internal call / reference graph and propose natural decomposition groups via Louvain community detection. Reports per-group isolation %, internal vs cross-group edges, and ranked extraction candidates (groups with >=3 symbols and >=50% isolation). Different from roam_clusters (repo-wide module partitioning) -- this analyses ONE file's internal seams.

roam_stale_refs

Find dangling file references — markdown links / HTML href-src / backtick paths whose target is missing. v12.48 adds anchor validation, confidence-tagged hints, --diff branch filter, --fix preview/apply, and --sort-by ranking. Set enrich_with_llm=True for LLM-sampled hints on findings the deterministic providers couldn't resolve.

roam_stats

Aggregate high-level statistics: language / role / kind counts plus a recent-commit activity counter over a configurable window. Different from roam_metrics (per-symbol static-metric report) and roam_graph_stats (graph-wide topology stats) -- this is the language-and-role inventory snapshot.

roam_suggest_refactoring

Rank proactive refactoring candidates using complexity/coupling/churn/smells.

roam_suggest_reviewers

Suggest optimal code reviewers for changed files.

roam_supply_chain

Dependency risk dashboard: pin coverage, risk scoring, supply-chain health.

roam_symbol

Symbol definition, callers, callees, PageRank, fan-in/out metrics.

roam_syntax_check

Tree-sitter syntax validation. Finds ERROR/MISSING AST nodes. No index needed.

roam_taint

Graph-reach taint analysis. Returns OpenVEX-shaped findings (spec-legal status + justification — never code_not_reachable). 10 starter rule packs: sqli, xss, ssrf, path-traversal, command-injection, deserialization, open-redirect, urllib, socketio, fileupload. Pair with --ci to gate on findings (exit 5).

roam_taint_classify

Run roam taint then ask the agent's own LLM (via MCP sampling) to classify each reachable finding as IDOR/AUTHZ/SQLI/XSS/CMD_INJECTION/etc. with confidence + reasoning. Counter to Semgrep Multimodal — same LLM-reasoning narrative without a hosted API key.

roam_test_gaps

Find changed symbols missing test coverage, ranked by severity.

roam_test_hermeticity

Detect non-hermetic test patterns that cause CI flakiness. Six closed-enum kinds: network, time, random, filesystem, env, subprocess. AST-driven (not regex) with module-level suppression for monkeypatch / freezegun / responses / random.seed.

roam_test_impact

Tests transitively reachable from changed symbols — sharper scope than affected_tests.

roam_test_map

Map a symbol or file to its current test coverage: direct test edges (test file calls the symbol), file-level importers (test file imports the symbol's module), and convention-based matches (Salesforce <Name>Test / <Name>_Test classes). Different from roam_test_gaps (untested symbols in changed files) and roam_affected_tests (forward trace from changes to affected tests) -- this is the lookup for what currently exercises a given symbol.

roam_test_pyramid

Count indexed test files by kind (unit / integration / e2e / smoke / unknown) using path and name conventions, and flag inverted pyramids (when e2e + integration > unit). Different from roam_test_gaps (missing coverage) -- this measures the shape of the existing test suite for slow-CI risk.

roam_test_scaffold

Generate a test-file skeleton for a source file or symbol (functions, classes, methods) with the right imports and per-symbol stub blocks. Supports pytest / unittest (Python), jest / mocha / vitest (JS/TS), Go testing, JUnit4 / JUnit5 (Java), and RSpec / Minitest (Ruby). Dry-run by default; pair with roam_test_map first to confirm no existing coverage. Skips symbols that already have tests in the target file.

roam_timeline

Chronological commits that touched the file owning a symbol — author, date, lines added/removed.

roam_tour

Codebase onboarding guide: reading order, entry points, architecture roles.

roam_trace

Shortest dependency path between two symbols with hop details.

roam_trends

Historical metric tracking: record and query health metric trends over time.

roam_tx_boundaries

Classify functions by transactional safety: transactional (begin matched by commit/rollback, all mutations inside scope), partial_transactional (mutations both inside AND outside scope), unsafe_mutation (mutations OUTSIDE any transaction wrapper -- latent bug), unmatched_begin (begin without commit/rollback -- leak), unmatched_commit, non_transactional, or unknown. Composes on top of roam_side_effects. Different from roam_idempotency (retry safety) -- this gates transaction correctness.

roam_understand

Brief Claude on an unfamiliar codebase in one call. Use when user asks 'what is this repo?', 'where do I start?', 'give me the lay of the land'. Returns stack, architecture layers, entry points, hotspots, conventions (~2-4K tokens). Do NOT explore with Glob/Grep first — start here.

roam_uses

List every caller, importer, and subclass of a symbol — structured by edge type. Use when user asks 'where is X used?', 'who calls Y?', 'what breaks if I rename Z?'. Graph-precise: no comment / string-literal false positives that multi-shape Grep produces. Do NOT use Bash:grep for references — this is the right tool. For 3+ symbols call roam_batch_get (one round-trip) instead.

roam_validate_plan

Pre-apply validator for a multi-step change plan. Returns blockers, warnings, advice per operation.

roam_verify

Check changed files for naming, import, error-handling, and duplicate issues.

roam_verify_imports

Hallucination firewall: validate import statements resolve to indexed symbols.

roam_vibe_check

AI rot score (0-100): 8-pattern taxonomy of AI code anti-patterns.

roam_visualize

Generate Mermaid/DOT architecture diagram with smart filtering.

roam_vuln_map

Ingest vulnerability scanner reports (npm/pip/trivy/osv), match to symbols.

roam_vuln_reach

Vulnerability reachability through call graph: paths, hops, blast radius.

roam_weather

Churn x complexity hotspot ranking: highest-leverage refactoring targets.

roam_why

Explain why a symbol matters: role classification (Hub/Bridge/Leaf), transitive reach, critical-path membership, cluster cohesion, and a one-line verdict. Accepts multiple symbol names for batch triage. Different from roam_fan (raw connectivity ranking) and roam_preflight (blast-radius gate before edit) -- this is the per-symbol role explainer for triage and onboarding.

roam_why_fail

Triage a failing test/symbol: recently-changed symbols transitively reachable from it.

roam_why_slow

Rank runtime hotspots by cost = log10(call_count + 1) * p99_latency_ms. Reads runtime_stats populated by roam ingest-trace. Optionally restricts to symbols in changed files vs a base ref. Different from roam_hotspots (static-vs-runtime classification) -- this is the pure latency-weighted ranking.

roam_workflow

Inspect a workflow recipe DAG, list available recipes, or suggest what to run next given a prior command. Useful as an agent navigation aid: 'I just ran roam impact -- what should I run next?' Different from the heavyweight analytical recipes -- this is the metadata-only recipe browser.

roam_ws_context

Cross-repo augmented context for a symbol spanning multiple repos.

roam_ws_understand

Multi-repo workspace overview: per-repo stats, cross-repo connections.

roam_x_lang

Show cross-language symbol bridges: Protobuf .proto -> generated Go/Java/Python stubs, Salesforce Apex -> Aura/LWC/Visualforce, REST API frontend -> backend route, template variable -> source, and env-var read -> .env definition. Call this tool to list every registered bridge type.

Language

Extensions

Symbols

References

Inheritance

Python

.py .pyi

classes, functions, methods, decorators, variables

imports, calls, inheritance

extends, __all__ exports

JavaScript

.js .jsx .mjs .cjs

classes, functions, arrow functions, CJS exports

imports, require(), calls

extends

TypeScript

.ts .tsx .mts .cts

interfaces, type aliases, enums + all JS

imports, calls, type refs

extends, implements

Java

.java

classes, interfaces, enums, constructors, fields

imports, calls

extends, implements

Go

.go

structs, interfaces, functions, methods, fields

imports, calls

embedded structs

Rust

.rs

structs, traits, impls, enums, functions

use, calls

impl Trait for Struct

C / C++

.c .h .cpp .hpp .cc

structs, classes, functions, namespaces, templates

includes, calls

extends

C#

.cs

classes, interfaces, structs, enums, records, methods, properties, delegates, events

using directives, calls, new, attributes

extends, implements

PHP

.php

classes, interfaces, traits, enums, methods, properties

namespace use, calls, static calls, new

extends, implements, use (traits)

Ruby

.rb

classes, modules, methods, singleton methods, constants

require, require_relative, include/extend, calls

class inheritance

Kotlin

.kt .kts

classes, interfaces, enums, objects, functions, methods, properties

imports, calls, type refs

extends, implements

Scala

.scala .sc

classes, traits, objects, case classes, functions, val/var, type aliases

imports, calls, new

extends, with (trait mixins)

Swift

.swift

classes, structs, enums, protocols, functions, methods, properties

imports, calls, type refs

extends, conforms

Dart

.dart

classes, mixins, extensions, enums, type aliases, functions, methods, constructors

imports, calls, type refs

extends, implements, with

Visual FoxPro

.prg

functions, procedures, classes, methods, properties, constants

DO, SET PROCEDURE/CLASSLIB, CREATEOBJECT, obj.method()

DEFINE CLASS ... AS

SQL (DDL)

.sql

tables, columns, views, functions, triggers, schemas, types, sequences

foreign keys, view table deps, trigger refs

—

YAML (CI/CD)

.yml .yaml

GitLab CI jobs/anchors, GitHub Actions workflows/jobs, generic top-level keys

extends:, needs:, !reference, uses:

—

HCL / Terraform

.tf .tfvars .hcl

resource, data, variable, output, module, provider, locals

var.*, module.*, data.*, local.*

—

Vue / Svelte

.vue .svelte

via <script> block extraction (TS/JS)

imports, calls, type refs

extends, implements

Language

Extensions

Symbols

References

Apex

.cls .trigger

classes, triggers, SOQL, annotations

imports, calls, System.Label, generic type refs

Aura

.cmp .app .evt .intf .design

components, attributes, methods, events

controller refs, component refs

LWC (JavaScript)

.js (in LWC dirs)

anonymous class from filename

@salesforce/apex/, @salesforce/schema/, @salesforce/label/

Visualforce

.page .component

pages, components

controller/extensions, merge fields, includes

SF Metadata XML

*-meta.xml

objects, fields, rules, layouts

Apex class refs, formula field refs, Flow actionCalls

Metric

Value

Index 200 files

~3-5s

Index 3,000 files

~2 min

Incremental (no changes)

<1s

Any query command

<0.5s

Capability

roam-code

AI IDEs (Cursor, Windsurf)

AI Agents (Claude Code, Codex)

SAST (SonarQube, CodeQL)

Persistent local index

SQLite

Cloud embeddings

None

Per-scan

Call graph analysis

Yes

No

No

Yes (CodeQL)

PageRank / centrality

Yes

No

No

No

Cycle detection (Tarjan)

Yes

No

No

Deprecated (SonarQube)

Community detection (Louvain)

Yes

No

No

No

Git churn / co-change

Yes

No

No

No

Architecture simulation

Yes

No

No

No

Multi-agent partitioning

Yes

No

No

No

MCP tools for agents

227 (57 in default core preset)

Client only

Client only

34 (SonarQube)

Languages

28

70+

50+

12-42

100% local, zero API keys

Yes

No

No

Partial

Open source

Apache 2.0

No

Partial

Partial

Interprocedural taint depth

shallow (OpenVEX-shaped)

n/a

n/a

deep (CodeQL)

Built-in rule packs

10 taint packs, 10 governance rules

n/a

n/a

2,000+ (Semgrep community)

Cross-repo at GitHub scale

workspace overlay (sibling repos)

n/a

n/a

native (Sourcegraph)

Tool

Annual cost (20-dev team)

Infrastructure

Setup time

SonarQube Server (paid tier)

$15,000-$45,000

Self-hosted server

Days

CodeScene

$20,000-$60,000

SaaS or on-prem

Hours

Code Climate

$12,000-$36,000

SaaS

Hours

Roam (free CLI)

$0 (Apache 2.0)

None (local)

5 minutes

Problem

Solution

roam: command not found

Ensure install location is on PATH. For uv: uv tool update-shell

Another indexing process is running

Delete .roam/index.lock and retry

database is locked

roam index --force to rebuild

Unicode errors on Windows

chcp 65001 for UTF-8

Symbol resolves to wrong file

Use file:symbol syntax: roam symbol myfile:MyFunction

Health score seems wrong

roam --json health for factor breakdown

Index stale after git pull

roam index (incremental). After major refactors: roam index --force