roam-code

Architectural sight for AI coding agents — before they edit.

A local code graph (SQLite + tree-sitter + git history) that gives any agent — Claude Code, Cursor, Aider, Continue, your own — five high-leverage verbs: understand, retrieve, context, preflight, critique. The other 150 specialised commands are advanced surface for specialised workflows.

155 commands · 122 MCP tools · 27 languages · 100% local · zero API keys

---

What is Roam?

Roam is a structural intelligence engine for software. It pre-indexes your codebase into a semantic graph -- symbols, dependencies, call graphs, architecture layers, git history, and runtime traces -- stored in a local SQLite DB. Agents query it via CLI or MCP instead of repeatedly grepping files and guessing structure.

Unlike LSPs (editor-bound, language-specific) or Sourcegraph (hosted search), Roam provides architecture-level graph queries -- offline, cross-language, and compact. It goes beyond comprehension: Roam governs architecture through budget gates, simulates refactoring outcomes, orchestrates multi-agent swarms with zero-conflict guarantees, maps vulnerability reachability paths, and enables graph-level code editing without syntax errors.

Codebase ──> [Index] ──> Semantic Graph ──> 155 Commands ──> AI Agent
              │              │                  │
           tree-sitter    symbols            comprehend
           27 languages   + edges            govern
           git history    + metrics          refactor
           runtime traces + architecture     orchestrate

Start here — the 5 verbs that cover ~80% of agent workflows

pip install roam-code

cd your-repo/
roam understand                       # 1. landing pad — what is this codebase?
roam retrieve "where is auth?"        # 2. graph-aware retrieval for free-form tasks
roam context AuthService              # 3. exact files+lines to read before changing
roam preflight AuthService            # 4. blast radius + tests + complexity check
git diff | roam critique              # 5. patch verifier — clones-not-edited, hot-path

That's the full mental model. The other CLI surface — taint, fleet, cga, simulate, mutate, partition, attest, eval-retrieve, oracle, py-types, py-modern, dark-matter, clones, propagation, fingerprint, etc. — is advanced surface for specialised workflows; you'll never need most of them.

The problem

Coding agents explore codebases inefficiently: dozens of grep/read cycles, high token cost, no structural understanding. Roam replaces this with one graph query:

$ roam context Flask
Callers: 47  Callees: 3
Affected tests: 31

Files to read:
  src/flask/app.py:76-963              # definition
  src/flask/__init__.py:1-15           # re-export
  src/flask/testing.py:22-45           # caller: FlaskClient.__init__
  tests/test_basic.py:12-30            # caller: test_app_factory
  ...12 more files

Terminal demo

Core commands

$ roam understand              # full codebase briefing
$ roam context <name>          # files-to-read with exact line ranges
$ roam retrieve "<task>"       # graph-aware spans for free-form natural-language tasks
$ roam preflight <name>        # blast radius + tests + complexity + architecture rules
$ roam critique                # verify a patch (`git diff | roam critique`)
$ roam health                  # composite score (0-100)
$ roam diff                    # blast radius of uncommitted changes

What's New in v12

v12.1+ -- Boolean oracles, IDOR classifier, index portability + Django bridge

• roam oracle <name>: 5 boolean oracles for agents — 1-token yes/no answers (symbol-exists, route-exists, is-test-only, is-reachable-from-entry, is-clone-of). Direct counter to CKB v9.2's symbolExists pattern. MCP tools: roam_oracle_*.
• roam_taint_classify (MCP only): LLM-augmented taint classification — runs roam taint then asks the agent's own model (via MCP sampling) to label each reachable finding as IDOR/AUTHZ/SQLI/XSS/etc. with confidence + reasoning. Counter to Semgrep Multimodal — same LLM-reasoning narrative without a hosted API key. Sequential for v12.1; concurrency-bounded gather lands in v12.2.
• roam index-export / roam index-import: portable, integrity-checked tarball format with manifest sha256 round-trip + optional cosign signing. Counter to Cursor's "92% similar codebase = reuse teammate's index" without a vendor cloud. Tamper-evident (manifest verifies index.db sha256 on import).
• roam eval-retrieve --emit-format coderag|beir: bench-portable JSONL emit for public leaderboard submission. CodeRAG-Bench-compatible ctxs array + BEIR-style trec_eval run files.
• Django bridge: full implicit-relationship resolution (admin→model, serializer→model, FK transitive, signal handlers, URL configs, Celery tasks, DRF routers). Ported from @LukasBerka/roam-code — credit Lukas Berka. New schema columns: framework_type, field_type, field_metadata. Post-resolver runs after graph metrics.
• worktree_git_env() (git_utils.py): GIT_INDEX_FILE override fixes .git/index.lock contention when parallel agents run roam in sibling worktrees. Wired into discovery.py, git_stats.py, changed_files.py. Ported from @river-mounts/roam-code-sf — credit Sam Hannan.

v12.0 (released 2026-05-01) -- Retrieval substrate + patch verifier

• roam retrieve "<task>": graph-aware context server. Hybrid first stage (FTS5) + structural reranker (personalised PageRank + clone-canonical signal + lexical baseline) + token-budget cap. Returns ranked spans with justification tags (pagerank=..., clone_cluster=..., fts=...) so callers can see why each span ranked. MCP tool: roam_retrieve(task, budget, k, rerank, seed_files).
• roam critique: graph-grounded patch verifier. Pipe git diff | roam critique to get findings ranked by severity. The killer signal is clones-not-edited: for every changed symbol with persisted clone siblings outside the diff, we flag the sibling as a likely missed change. Plus a blast-radius caller-count finding. Exits 5 on high severity (CI-gateable). MCP tool: roam_critique(diff_text).
• roam clones --persist: populate the clone_pairs and clone_clusters tables so downstream consumers (critique, retrieve) can query clones in O(1) instead of re-running detection.
• personalized_pagerank() in graph/pagerank.py: NetworkX personalization= wrapper with empty-seed fallback to global PR; biases ranking toward query-relevant nodes for the retrieve reranker.
• .roam/config.toml (new): zero-dep TOML loader (stdlib tomllib → tomli → in-tree subset parser). Tunable retrieve weights (alpha/beta/gamma/delta/epsilon), tokens_per_line, lexical_baseline, first_stage_token_cap, default_budget, default_k, default_rerank.
• DX corrections from dogfood pass: roam --detail <cmd> is the canonical group-level flag; misleading "use --detail" hints in 7 commands rewritten to point users at roam --detail <cmd>. --top N aliased on complexity/algo/rules (--top 0 means unlimited on rules). roam fingerprint no longer refuses graphs ≥5,000 symbols (new soft-warn threshold 20k, hard cap 100k).
• 155 CLI commands, 122 MCP tools (fleet, ask, workflow, cga, eval-retrieve remain CLI-only; v12 exposes roam_retrieve, roam_critique, roam_fleet_plan, plus 5 v12.1 boolean oracles (roam_oracle_*), roam_taint_classify, roam_pytest_fixtures, and roam_hover as MCP tools). 35-tool core preset is the default for token-budget-conscious clients.

What's New in v11

v11.2 -- AST Clone Detection + Debug Artifact Rules

• roam clones: New AST structural clone detection via subtree hashing. Finds Type-2 clones (identical control flow, different identifiers/literals) with Jaccard similarity scoring, Union-Find clustering, and automated refactoring suggestions. More precise than the metric-based duplicates command.
• 9 debug artifact rules (COR-560 through COR-568): Detect leftover print(), breakpoint(), pdb.set_trace(), console.log(), debugger, and System.out.println() in Python, JavaScript, TypeScript, and Java code. All use ast_match type with test file exemptions.
• 140 commands, 102 MCP tools (at v11.2.0 release).

v11.1.2 -- SQL + Scala Tier 1, 27 Languages

• SQL DDL promoted to Tier 1 with dedicated SqlExtractor -- tables, columns, views, functions, triggers, schemas, types (enums), sequences, ALTER TABLE ADD COLUMN. Foreign keys produce graph edges; views and triggers reference source tables. Database-schema projects now work with roam health, roam layers, roam impact, roam coupling and all graph commands.
• Scala promoted to Tier 1 with dedicated ScalaExtractor -- classes, traits, objects, case classes, sealed hierarchies, val/var properties, type aliases, imports, and inheritance. Full extends + with trait mixin resolution.
• 27 languages with 16 dedicated Tier 1 extractors.
• server.json for official MCP Registry submission.

v11.1.1 -- Command Quality Audit

• Full command audit: all 152 commands reviewed for usefulness, duplicates, and test coverage. ~20 bugs fixed, 21 new test files (700+ tests), every command docstring updated with cross-references to related commands.
• Kotlin promoted to Tier 1 via new YAML-based declarative extractor architecture. Classes, interfaces, enums, objects, functions, methods, properties, and inheritance fully extracted.
• 7 new commands: roam congestion, roam adrs, roam flag-dead, roam test-scaffold, roam sbom, roam triage, roam ci-setup.
• CI templates: roam ci-setup generates pipelines for GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and Bitbucket.
• Bug fixes: --undocumented mode in intent (wrong DB table), --changed flag in verify (was permanently dead), lazy-load violation in visualize (~500ms penalty), exit code inconsistency in rules, VERDICT-first convention enforced across all commands.
• Code quality: 15 unused variables removed, dead code swept (4 orphaned cmd files, 2 dead helper functions), algo detector false-positive rate reduced (regex-in-loop: 7 to 1, list-prepend deque suppression), 6 regex patterns pre-compiled for loop performance.

v11.0 -- MCP v2 for Agent-First Workflows

• In-process MCP execution removes per-call subprocess overhead.
• 4 compound operations (roam_explore, roam_prepare_change, roam_review_change, roam_diagnose_issue) reduce multi-step agent workflows to single calls.
• Preset-based tool surfacing (core, review, refactor, debug, architecture, full) keeps default tool choice tight for agents while retaining full depth on demand.
• MCP tools now expose structured schemas and richer annotations for safer planner behavior.
• MCP token overhead for default core context dropped from ~36K to <3K tokens (about 92% reduction).

Performance and Retrieval

• Symbol search moved to SQLite FTS5/BM25: typical search moved from seconds to tens of milliseconds on the indexed cohort (mileage varies by repo size and query selectivity — see bench/retrieve/ for the methodology).
• Incremental indexing shifted from O(N) full-edge rebuild behavior to O(changed) updates.
• DB/runtime optimizations (mmap_size, safer large-graph guards, batched writes) reduce first-run and reindex friction on larger repos.

CI, Governance, and Delivery

• GitHub Action supports quality gates, SARIF upload, sticky PR comments, and cache-aware execution.
• CI hardening includes changed-only analysis mode, trend-aware gates, and SARIF pre-upload guardrails (size/result caps + truncation signaling).
• Agent governance expanded with verification and AI-quality tooling (roam verify, roam vibe-check, roam ai-readiness, roam ai-ratio) for teams managing agent-written code.

Best for

• Agent-assisted coding -- structured answers that reduce token usage vs raw file exploration
• Large codebases (100+ files) -- graph queries beat linear search at scale
• Architecture governance -- health scores, CI quality gates, budget enforcement, fitness functions
• Safe refactoring -- blast radius, affected tests, pre-change safety checks, graph-level editing
• Multi-agent orchestration -- partition codebases for parallel agent work with zero-conflict guarantees
• Security analysis -- vulnerability reachability mapping, auth gaps, CVE path tracing
• Algorithm optimization -- detect O(n^2) loops, N+1 queries, and 21 other anti-patterns with suggested fixes
• Backend quality -- auth gaps, missing indexes, over-fetching models, non-idempotent migrations, orphan routes, API drift
• Runtime analysis -- overlay production trace data onto the static graph for hotspot detection
• Multi-repo projects -- cross-repo API edge detection between frontend and backend

When NOT to use Roam

• Real-time type checking -- use an LSP (pyright, gopls, tsserver). Roam is static and offline.
• Small scripts (<10 files) -- just read the files directly.
• Pure text search -- ripgrep is faster for raw string matching.

Why use Roam

Speed. One command replaces 5-10 tool calls (in typical workflows). Under 0.5s for any query.

Dependency-aware. Computes structure, not string matches. Knows Flask has 47 dependents and 31 affected tests. grep knows it appears 847 times.

LLM-optimized output. Plain ASCII, compact abbreviations (fn, cls, meth), --json envelopes. Designed for agent consumption, not human decoration.

Fully local. No API keys, telemetry, or network calls. Works in air-gapped environments.

Algorithm-aware. Built-in catalog of 23 anti-patterns. Detects suboptimal algorithms (quadratic loops, N+1 queries, unbounded recursion) and suggests fixes with Big-O improvements and confidence scores. Receiver-aware loop-invariant analysis minimizes false positives.

CI-ready. --json output, --gate quality gates, GitHub Action, SARIF 2.1.0.

| | Without Roam | With Roam | |--|-------------|-----------| | Tool calls | 8 | 1 | | Wall time | ~11s | <0.5s | | Tokens consumed | ~15,000 | ~3,000 |

Measured on a typical agent workflow in a 200-file Python project (Flask). See benchmarks for more.

Getting Started: What is Roam? · What's New in v11 · Best for · Why use Roam · Install · Quick Start

Using Roam: Commands · Walkthrough · AI Coding Tools · MCP Server

Operations: CI/CD Integration · SARIF Output · For Teams

Reference: Language Support · Performance · How It Works · How Roam Compares · FAQ

More: Limitations · Troubleshooting · Update / Uninstall · Development · Contributing

Install

pip install roam-code

# Recommended: isolated environment
pipx install roam-code
# or
uv tool install roam-code

# From source
pip install git+https://github.com/Cranot/roam-code.git

Requires Python 3.9+. Works on Linux, macOS, and Windows.

Windows: If roam is not found after installing with uv, run uv tool update-shell and restart your terminal.

Docker (alpine-based)

docker build -t roam-code .
docker run --rm -v "$PWD:/workspace" roam-code index
docker run --rm -v "$PWD:/workspace" roam-code health

Quick Start

cd your-project
roam init                  # indexes codebase, creates config + CI workflow
roam understand            # full codebase briefing

First index takes ~5s for 200 files, ~15s for 1,000 files. Subsequent runs are incremental and near-instant.

Next steps:

• Set up your AI agent: roam describe --write (auto-detects CLAUDE.md, AGENTS.md, .cursor/rules, etc. — see integration instructions)
• Explore: roam health → roam weather → roam map
• Add to CI: roam init already generated a GitHub Action

git clone https://github.com/Cranot/roam-code.git
cd roam-code
pip install -e .
roam init
roam understand
roam health

Works With

Commands

Lead with the 5 verbs. The 5 core commands cover ~80% of agent workflows: understand, context, retrieve, preflight, critique. The remaining 150 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is 155 commands organised into 7 categories (plus 6 aliases for muscle memory: algo → math, weather → churn, digest / snapshot / trend → trends, onboard → understand), but you don't need to know that to start.

Getting Started

| Command | Description | |---------|-------------| | roam index [--force] [--verbose] | Build or rebuild the codebase index | | roam index-export <bundle.tar.gz> [--sign] [--key K] [--keyless] | Export the indexed .roam/index.db as a signed, integrity-checked tarball. Counter to Cursor's "reuse teammate's index" without a vendor cloud. | | roam index-import <bundle.tar.gz> [--force] [--cosign-bundle B] [--cosign-key K] | Import a portable index bundle. Verifies manifest sha256 + optional cosign signature; refuses to overwrite without --force. | | roam watch [--interval N] [--debounce N] [--webhook-port P] [--guardian] | Long-running index daemon: poll/webhook-triggered refreshes plus optional continuous architecture-guardian snapshots and JSONL compliance artifacts | | roam init | Guided onboarding: creates .roam/fitness.yaml, CI workflow, runs index, shows health | | roam hooks [--install] [--uninstall] | Manage git hooks for automated roam index updates and health gates | | roam doctor | Diagnose installation and environment: verify tree-sitter grammars, SQLite, git, and config health | | roam reset [--hard] | Reset the roam index and cached data. --hard removes all .roam/ artifacts | | roam clean [--all] | Remove stale or orphaned index entries without a full rebuild | | roam understand | Full codebase briefing: tech stack, architecture, key abstractions, health, conventions, complexity overview, entry points | | roam onboard | Alias for understand | | roam tour [--write PATH] | Auto-generated onboarding guide: top symbols, reading order, entry points, language breakdown. --write saves to Markdown | | roam describe [--write] [--force] [-o PATH] [--agent-prompt] | Auto-generate project description for AI agents. --write auto-detects your agent's config file. --agent-prompt returns a compact (<500 token) system prompt | | roam agent-export [--format F] [--write] | Generate agent-context bundle from project analysis (AGENTS.md + provider-specific overlays) | | roam minimap [--update] [-o FILE] [--init-notes] | Compact annotated codebase snapshot for agent config injection: stack, annotated directory tree, key symbols by PageRank, high fan-in symbols to avoid touching, hotspots, conventions. Sentinel-based in-place updates | | roam config [--set-db-dir PATH] [--use-local-cache] [--semantic-status] [--semantic-backend MODE] | Manage .roam/config.json (DB path, local cache storage, excludes, optional ONNX semantic settings, and activation diagnostics) | | roam map [-n N] [--full] [--budget N] | Project skeleton: files, languages, entry points, top symbols by PageRank. --budget caps output to N tokens | | roam schema [--diff] [--version V] | JSON envelope schema versioning: view, diff, and validate output schemas | | roam mcp [--list-tools] [--transport T] | Start MCP server (stdio/SSE/streamable-http), inspect available tools, and expose roam to coding agents | | roam mcp-setup <platform> | Generate MCP config snippets for AI platforms: claude-code, cursor, windsurf, vscode, gemini-cli, codex-cli | | roam ci-setup [--platform P] [--write] | Generate CI/CD pipeline config (GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, Bitbucket) with SARIF + quality gates | | roam adrs [--status S] [--limit N] | Discover Architecture Decision Records, link to affected code modules, show status and coverage |

Daily Workflow

| Command | Description | |---------|-------------| | roam file <path> [--full] [--changed] [--deps-of PATH] | File skeleton: all definitions with signatures, cognitive load index, health score | | roam symbol <name> [--full] | Symbol definition + callers + callees + metrics. Supports file:symbol disambiguation | | roam context <symbol> [--task MODE] [--for-file PATH] | AI-optimized context: definition + callers + callees + files-to-read with line ranges | | roam hover <symbol> | One-line architectural summary: kind, location, blast-radius bucket, top caller, top callee. Bounded at ~200 tokens for IDE hover panels | | roam retrieve <task> [--budget N] [--k N] [--seed-files PATH] | Graph-aware context for free-form tasks: FTS5 + structural rerank (PageRank + clones) + token budget | | roam critique [--input DIFF] [--intent TEXT] [--high-callers N] | Verify a patch against the graph: clones-not-edited + blast radius + intent-vs-semantic-diff. Pipe git diff in. Exit 5 on high severity. | | roam fleet plan <goal> [--n-agents N] [--adapter raw\|composio\|copilot] | Graph-aware planner: Louvain partition + co-change + PageRank anchors → .roam-fleet.json for Composio/Copilot CLI/raw. | | roam ask <query> [--list] [--explain] [--recipe NAME] | One-phrase intent classifier over a 13-recipe registry with phase, review-lens, gate, and follow-up metadata — composes preflight/retrieve/critique/fleet/understand/diagnose/trace/trends/hotspots/debt/taint/dead/coupling to cover the most common workflows. | | roam workflow [RECIPE] [--list] [--query TEXT] | Inspect a recipe DAG, review lenses, gates, rendered command arguments, and follow-up commands without running the workflow. | | roam taint [--rules-dir PATH] [--rule NAME] [--rules-pack PACK] [--ci] | Graph-reach taint analysis with OpenVEX-correct VEX justifications. YAML rule packs (10 starter packs: sqli, xss, ssrf, path-traversal, command-injection, deserialization, open-redirect, urllib, socketio, fileupload). | | roam cga emit [--include-taint] [--sign --key] | Code Graph Attestation — in-toto v1 statement with roam-code.dev/CodeGraph/v1 predicate, Merkle root + edge bundle digest. --include-taint embeds OpenVEX-shaped reachability claims from roam taint. --sign signs with cosign (graceful skip if absent); roam cga verify round-trips both predicate digest and cosign signature. | | roam eval-retrieve [--tasks FILE] [--sweep] [--min-recall-at-20 N] [--emit-format coderag\|beir] | Recall@K eval harness for roam retrieve — measures against a JSONL ground-truth file. CI-gateable. --emit-format coderag writes CodeRAG-Bench-compatible run files for public leaderboard submission. | | roam oracle <name> <subject> | Boolean oracles for agents — 1-token yes/no answers. Subcommands: symbol-exists, route-exists, is-test-only, is-reachable-from-entry, is-clone-of. | | roam search <pattern> [--kind KIND] | Find symbols by name pattern, PageRank-ranked | | roam grep <pattern> [-g glob] [-n N] | Text search annotated with enclosing symbol context | | roam deps <path> [--full] | What a file imports and what imports it | | roam trace <source> <target> [-k N] | Dependency paths with coupling strength and hub detection | | roam impact <symbol> | Blast radius: what breaks if a symbol changes (Personalized PageRank weighted) | | roam diff [--staged] [--full] [REV_RANGE] | Blast radius of uncommitted changes or a commit range | | roam pr-risk [REV_RANGE] | PR risk score (0-100, multiplicative model) + structural spread + suggested reviewers | | roam pr-diff [--staged] [--range R] [--format markdown] | Structural PR diff: metric deltas, edge analysis, symbol changes, footprint. Not text diff — graph delta | | roam api-changes [REV_RANGE] | API change classifier: breaking/non-breaking changes, severity, and affected contracts | | roam semantic-diff [REV_RANGE] | Structural change summary: symbols added/removed/modified and changed call edges | | roam test-gaps [REV_RANGE] | Changed-symbol test gap detection: what changed and what still lacks test coverage | | roam affected [REV_RANGE] | Monorepo/package impact analysis: what components are affected by a change | | roam attest [REV_RANGE] [--format markdown] [--sign] | Proof-carrying PR attestation: bundles blast radius, risk, breaking changes, fitness, budget, tests, effects into one verifiable artifact | | roam annotate <symbol> <note> | Attach persistent notes to symbols (agentic memory across sessions) | | roam annotations [--file F] [--symbol S] | View stored annotations | | roam diagnose <symbol> [--depth N] | Root cause analysis: ranks suspects by z-score normalized risk | | roam preflight <symbol\|file> | Compound pre-change check: blast radius + tests + complexity + coupling + fitness | | roam guard <symbol> | Compact sub-agent preflight bundle: definition, 1-hop callers/callees, test files, breaking-risk score, and layer signals | | roam agent-plan --agents N | Decompose partitions into dependency-ordered agent tasks with merge sequencing and handoffs | | roam agent-context --agent-id N [--agents M] | Generate per-agent execution context: write scope, read-only dependencies, and interface contracts | | roam syntax-check [--changed] [PATHS...] | Tree-sitter syntax integrity check for changed files and multi-agent judge workflows | | roam verify [--threshold N] | Pre-commit AI-code consistency check across naming, imports, error handling, and duplication signals | | roam verify-imports [--file F] | Import hallucination firewall: validate all imports against indexed symbol table, suggest corrections via FTS5 fuzzy matching | | roam triage list\|add\|stats\|check | Security finding suppression workflow: manage .roam-suppressions.yml (SAFE/ACKNOWLEDGED/WONT-FIX status lifecycle) | | roam safe-delete <symbol> | Safe deletion check: SAFE/REVIEW/UNSAFE verdict | | roam test-map <name> | Map a symbol or file to its test coverage | | roam adversarial [--staged] [--range R] | Adversarial architecture review: generates targeted challenges based on changes | | roam plan [--staged] [--range R] [--agents N] | Agent work planner: decompose changes into sequenced, dependency-aware steps | | roam closure <symbol> [--rename] [--delete] | Minimal-change synthesis: all files to touch for a safe rename/delete | | roam mutate move\|rename\|add-call\|extract | Graph-level code editing: move symbols, rename across codebase, add calls, extract functions. Dry-run by default |

Codebase Health

| Command | Description | |---------|-------------| | roam health [--no-framework] [--gate] | Composite health score (0-100): weighted geometric mean of tangle ratio, god components, bottlenecks, layer violations. --gate runs quality gate checks from .roam-gates.yml (exit 5 on failure) | | roam smells [--file F] [--min-severity S] | Code smell detection: 15 deterministic detectors (brain methods, god classes, feature envy, shotgun surgery, data clumps, etc.) with per-file health scores | | roam dashboard | Unified single-screen project status: health, hotspots, risks, ownership, and AI-rot indicators | | roam vibe-check [--threshold N] | AI-rot auditor: 8-pattern taxonomy with composite risk score and prioritized findings | | roam ai-readiness | 0-100 score for how well this codebase supports AI coding agents | | roam ai-ratio [--since N] | Statistical estimate of AI-generated code ratio using commit-behavior signals | | roam trends [--record] [--days N] [--metric M] | Historical metrics snapshots with sparklines and trend deltas | | roam complexity [--bumpy-road] [--include-tooling] | Per-function cognitive complexity (SonarSource-compatible, triangular nesting penalty) + Halstead metrics (volume, difficulty, effort, bugs) + cyclomatic density | | roam py-types [--detail] [--include-tests] [--ci --min-coverage N] | Python type-annotation health: % of public functions with full annotations, Any usage, legacy typing.Optional/Dict/List (PEP 585/604 modernisation candidates), per-file worst offenders. CI-gateable via --ci --min-coverage N (exit 5 below threshold). Default-excludes test files | | roam py-modern [--detail] | Modern-Python adoption signal: counts walrus operator (PEP 572), match statements (PEP 634), PEP 604 X \| None, PEP 585 dict[…], PEP 695 type aliases, f-strings vs .format(). Reports type-modernisation % and f-string adoption % to gauge migration progress | | roam pytest-fixtures [SYMBOL] [--max-depth N] | Inventory pytest fixture chains. With no SYMBOL, prints the project-wide fixture count and the top fixtures by dependent count. With a fixture or test name, walks the implicit fixture-parameter dependency graph to show what each test transitively requires. Resolves through conftest.py chains | | roam algo [--task T] [--confidence C] [--profile P] | Algorithm anti-pattern detection: 23-pattern catalog detects suboptimal algorithms (O(n^2) loops, N+1 queries, quadratic string building, branching recursion, loop-invariant calls) and suggests better approaches with Big-O improvements. Confidence calibration via caller-count + runtime traces, evidence paths, impact scoring, framework-aware N+1 packs, and language-aware fix templates. Alias: roam math | | roam n1 [--confidence C] [--verbose] | Implicit N+1 I/O detection: finds ORM model computed properties ($appends/accessors) that trigger lazy-loaded DB queries in collection contexts. Cross-references with eager loading config. Supports Laravel, Django, Rails, SQLAlchemy, JPA | | roam over-fetch [--threshold N] [--confidence C] | Detect models serializing too many fields: large $fillable without $hidden/$visible, direct controller returns bypassing API Resources, poor exposed-to-hidden ratio | | roam missing-index [--table T] [--confidence C] | Find queries on non-indexed columns: cross-references WHERE/ORDER BY clauses, foreign keys, and paginated queries against migration-defined indexes | | roam weather [-n N] | Hotspots ranked by geometric mean of churn x complexity (percentile-normalized) | | roam debt [--roi] | Hotspot-weighted tech debt prioritization with SQALE remediation costs and optional refactoring ROI estimates | | roam fitness [--explain] [--baseline PATH] [--write-baseline] | Architectural fitness functions from .roam/fitness.yaml, with baseline/delta mode for existing debt | | roam alerts | Health degradation trend detection (Mann-Kendall + Sen's slope) | | roam forecast [--symbol S] [--horizon N] [--alert-only] | Predict when metrics will exceed thresholds: Theil-Sen regression on snapshot history + churn-weighted per-symbol risk | | roam budget [--init] [--staged] [--range R] | Architectural budget enforcement: per-PR delta limits on health, cycles, complexity. CI gate (exit 5 on violation) | | roam bisect [--metric M] [--range R] | Architectural git bisect: find the commit that degraded a specific metric | | roam ingest-trace <file> [--otel\|--jaeger\|--zipkin\|--generic] | Ingest runtime trace data (OpenTelemetry, Jaeger, Zipkin) for hotspot overlay | | roam hotspots [--runtime] [--discrepancy] | Runtime hotspot analysis: find symbols missed by static analysis but critical at runtime |

roam algo scans every indexed function against a 23-pattern catalog, ranks findings by runtime-aware impact score, and shows the exact Big-O improvement available. Findings include semantic evidence paths, precision metadata, and language-aware tips/fixes (Python, JS, Go, Rust, Java, etc.):

$ roam algo
VERDICT: 8 algorithmic improvements found (3 high, 4 medium, 1 low)
Ordering: highest impact first
Profile: balanced (filtered 0 low-signal findings)

Nested loop lookup (2):
  fn   resolve_permissions          src/auth/rbac.py:112     [high, impact=86.4]
        Current: Nested iteration -- O(n*m)
        Better:  Hash-map join -- O(n+m)
        Tip: Build a dict/set from one collection, iterate the other

  fn   find_matching_rule           src/rules/engine.py:67   [high, impact=78.1]
        Current: Nested iteration -- O(n*m)
        Better:  Hash-map join -- O(n+m)
        Tip: Build a dict/set from one collection, iterate the other

String building (1):
  meth build_query                  src/db/query.py:88       [high, impact=74.0]
        Current: Loop concatenation -- O(n^2)
        Better:  Join / StringBuilder -- O(n)
        Tip: Collect parts in a list, join once at the end

Branching recursion without memoization (1):
  fn   compute_cost                 src/pricing/calc.py:34   [medium, impact=49.5]
        Current: Naive branching recursion -- O(2^n)
        Better:  Memoized / iterative DP -- O(n)
        Tip: Add @cache / @lru_cache, or convert to iterative with a table

Full catalog — 23 patterns:

| Pattern | Anti-pattern detected | Better approach | Improvement | |---------|----------------------|-----------------|-------------| | Nested loop lookup | for x in a: for y in b: if x==y | Hash-map join | O(n·m) → O(n+m) | | Membership test | if x in list in a loop | Set lookup | O(n) → O(1) per check | | Sorting | Bubble / selection sort | Built-in sort | O(n²) → O(n log n) | | Search in sorted data | Linear scan on sorted sequence | Binary search | O(n) → O(log n) | | String building | s += chunk in loop | join() / StringBuilder | O(n²) → O(n) | | Deduplication | Nested loop dedup | set() / dict.fromkeys | O(n²) → O(n) | | Max / min | Manual tracking loop | max() / min() | idiom | | Accumulation | Manual accumulator | sum() / reduce() | idiom | | Group by key | Manual key-existence check | defaultdict / groupingBy | idiom | | Fibonacci | Naive recursion | Iterative / @lru_cache | O(2ⁿ) → O(n) | | Exponentiation | Loop multiplication | pow(b, e, mod) | O(n) → O(log n) | | GCD | Manual loop | math.gcd() | O(n) → O(log n) | | Matrix multiply | Naive triple loop | NumPy / BLAS | same asymptotic, ~1000× faster via SIMD | | Busy wait | while True: sleep() poll | Event / condition variable | O(k) → O(1) wake-up | | Regex in loop | re.match() compiled per iteration | Pre-compiled pattern | O(n·(p+m)) → O(p + n·m) | | N+1 query | Per-item DB / API call in loop | Batch WHERE IN (...) | n round-trips → 1 | | List front operations | list.insert(0, x) in loop | collections.deque | O(n) → O(1) per op | | Sort to select | sorted(x)[0] or sorted(x)[:k] | min() / heapq.nsmallest | O(n log n) → O(n) or O(n log k) | | Repeated lookup | .index() / .contains() inside loop | Pre-built set / dict | O(m) → O(1) per lookup | | Branching recursion | Naive f(n-1) + f(n-2) without cache | @cache / iterative DP | O(2ⁿ) → O(n) | | Quadratic string building | result += chunk across multiple scopes | parts.append + join at end | O(n²) → O(n) | | Loop-invariant call | get_config() / compile_schema() inside loop body | Hoist before loop | per-iter cost → O(1) | | String reversal | Manual char-by-char loop | s[::-1] / .reverse() | idiom |

Filtering:

roam algo --task nested-lookup       # one pattern type only
roam algo --confidence high          # high-confidence findings only
roam algo --profile strict           # precision-first filtering
roam algo --task io-in-loop -n 5    # top 5 N+1 query sites
roam --json algo                     # machine-readable output
roam --sarif algo > roam-algo.sarif  # SARIF with fingerprints + fixes

Confidence calibration: high = strong structural signal (unbounded loop + high caller/runtime impact + pattern confirmed); medium = pattern matched but uncertainty remains; low = heuristic signal only.

Profiles: balanced (default), strict (precision-first), aggressive (surface more candidates).

roam minimap generates a compact block (stack, annotated directory tree, key symbols, hotspots, conventions) wrapped in sentinel comments for in-place agent config updates:

$ roam minimap
<!-- roam:minimap generated=2026-02-25 -->
**Stack:** Python · JavaScript · YAML

.github/ (CI + Action) benchmarks/ (agent-eval + oss-eval) src/ roam/ bridges/ base.py # LanguageBridge registry.py # register_bridge, detect_bridges commands/ (137 cmd files) # is_test_file, get_changed_files db/ connection.py # find_project_root, batched_in schema.py graph/ builder.py # build_symbol_graph, build_file_graph pagerank.py # compute_pagerank, compute_centrality languages/ (21 files) # ApexExtractor output/ formatter.py # to_json, json_envelope cli.py # cli, LazyGroup mcp_server.py tests/ (186 files) `

Key symbols (PageRank): open_db · ensure_index · json_envelope · to_json · LanguageExtractor

Touch carefully (fan-in >= 15): to_json (116 callers) · json_envelope (116 callers) · open_db (105 callers) · ensure_index (100 callers)

Hotspots (churn x complexity): cmd_context.py · csharp_lang.py · cmd_dead.py

Conventions: snake_case fns, PascalCase classes

**Workflow:**

```bash
roam minimap                    # print to stdout
roam minimap --update           # replace sentinel block in CLAUDE.md in-place
roam minimap -o docs/AGENTS.md  # target a different file
roam minimap --init-notes       # scaffold .roam/minimap-notes.md for project gotchas

The sentinel pair <!-- roam:minimap --> / <!-- /roam:minimap --> is replaced on each run — surrounding content is left intact. Add project-specific gotchas to .roam/minimap-notes.md and they appear in every subsequent output.

Tree annotations come from the top exported symbols by fan-in per file. Non-source root directories (.github/, benchmarks/, docs/) are collapsed immediately. Large subdirectories (e.g. commands/, languages/) are collapsed at depth 2+ with a file count.

Architecture

| Command | Description | |---------|-------------| | roam clusters [--min-size N] | Community detection vs directory structure. Modularity Q-score (Newman 2004) + per-cluster conductance | | roam spectral [--depth N] [--compare] [--gap-only] [--k K] | Spectral bisection: Fiedler vector partition tree with algebraic connectivity gap verdict | | roam layers | Topological dependency layers + upward violations + Gini balance | | roam dead [--all] [--summary] [--clusters] | Unreferenced exported symbols with safety verdicts + confidence scoring (60-95%) | | roam flag-dead [--config FILE] [--include-tests] | Feature flag dead code detection: stale LaunchDarkly/Unleash/Split/custom flags with staleness analysis | | roam fan [symbol\|file] [-n N] [--no-framework] | Fan-in/fan-out: most connected symbols or files | | roam risk [-n N] [--domain KW] [--explain] | Domain-weighted risk ranking | | roam why <name> [name2 ...] | Role classification (Hub/Bridge/Core/Leaf), reach, criticality | | roam split <file> | Internal symbol groups with isolation % and extraction suggestions | | roam entry-points | Entry point catalog with protocol classification | | roam patterns | Architectural pattern recognition: Strategy, Factory, Observer, etc. | | roam visualize [--format mermaid\|dot] [--focus NAME] [--limit N] | Generate Mermaid or DOT architecture diagrams. Smart filtering via PageRank, cluster grouping, cycle highlighting | | roam effects [TARGET] [--file F] [--type T] | Side-effect classification: DB writes, network I/O, filesystem, global mutation. Direct + transitive effects through call graph | | roam dark-matter [--min-cochanges N] | Detect hidden co-change couplings not explained by import/call edges | | roam simulate move\|extract\|merge\|delete | Counterfactual architecture simulator: test refactoring ideas in-memory, see metric deltas before writing code | | roam orchestrate --agents N [--files P] | Multi-agent swarm partitioning: split codebase for parallel agents with zero-conflict guarantees | | roam partition [--agents N] | Multi-agent partition manifest: conflict risk, complexity, and suggested ownership splits | | roam fingerprint [--compact] [--compare F] | Topology fingerprint: extract/compare architectural signatures across repos | | roam cut <target> [--depth N] | Minimum graph cuts: find critical edges whose removal disconnects components | | roam safe-zones | Graph-based containment boundaries | | roam coverage-gaps | Unprotected entry points with no path to gate symbols | | roam duplicates [--threshold T] [--min-lines N] | Semantic duplicate detector: functionally equivalent code clusters with divergent edge-case handling | | roam clones [--threshold T] [--min-lines N] [--scope P] | AST structural clone detection: Type-2 clones via subtree hashing (more precise than duplicates) |

Exploration

| Command | Description | |---------|-------------| | roam module <path> | Directory contents: exports, signatures, dependencies, cohesion | | roam sketch <dir> [--full] | Compact structural skeleton of a directory | | roam uses <name> | All consumers: callers, importers, inheritors. Use this instead of grep "->X\|\.X\\b\|'X'\|\"X\"" to find references — graph-precise, no string-literal / comment false positives, structured by edge type. Available as roam refs <name> for grep-familiar muscle memory. | | roam owner <path> | Code ownership: who owns a file or directory | | roam coupling [-n N] [--set] | Temporal coupling: file pairs that change together (NPMI + lift) | | roam fn-coupling | Function-level temporal coupling across files | | roam bus-factor [--brain-methods] | Knowledge loss risk per module | | roam doc-staleness | Detect stale docstrings | | roam docs-coverage | Public-symbol doc coverage + stale docs + PageRank-ranked missing-doc hotlist | | roam suggest-refactoring [--limit N] [--min-score N] | Proactive refactoring recommendations ranked by complexity, coupling, churn, smells, coverage gaps, and debt | | roam plan-refactor <symbol> [--operation auto\|extract\|move] | Ordered refactor plan with blast radius, test gaps, layer risk, and simulation-based strategy preview | | roam test-scaffold <name\|file> [--write] [--framework F] | Generate test file/function/import skeletons from symbol data (pytest, jest, Go, JUnit, RSpec) | | roam conventions | Auto-detect naming styles, import preferences. Flags outliers | | roam breaking [REV_RANGE] | Breaking change detection: removed exports, signature changes | | roam affected-tests <symbol\|file> | Trace reverse call graph to test files | | roam relate <sym1> <sym2> | Show relationship between two symbols: shared callers, shortest path, common ancestors | | roam endpoints [--routes] [--api] | Enumerate all HTTP/API endpoint definitions and surface them for review or cross-repo matching | | roam metrics <file\|symbol> | Unified vital signs: complexity, fan-in/out, PageRank, churn, test coverage, dead code risk -- all in one call | | roam search-semantic <query> | Hybrid semantic search: BM25 + TF-IDF + optional local ONNX vectors (select via --backend) with framework/library packs | | roam intent [--staged] [--range R] | Doc-to-code linking: match documentation to symbols, detect drift | | roam x-lang [--bridges] [--edges] | Cross-language edge browser: inspect bridge-resolved connections |

Reports & CI

| Command | Description | |---------|-------------| | roam report [--list] [--config FILE] [PRESET] | Compound presets: first-contact, security, pre-pr, refactor, guardian | | roam describe --write | Generate agent config (auto-detects: CLAUDE.md, AGENTS.md, .cursor/rules, etc.) | | roam auth-gaps [--routes-only] [--controllers-only] [--min-confidence C] | Find endpoints missing authentication or authorization: routes outside auth middleware groups, CRUD methods without $this->authorize() / Gate::allows() checks. String-aware PHP brace parsing | | roam orphan-routes [-n N] [--confidence C] | Detect backend routes with no frontend consumer: parses route definitions, searches frontend for API call references, reports controller methods with no route mapping | | roam migration-safety [-n N] [--include-archive] | Detect non-idempotent migrations: missing hasTable/hasColumn guards, raw SQL without IF NOT EXISTS, index operations without existence checks | | roam api-drift [--model M] [--confidence C] | Detect mismatches between PHP model $fillable/$appends fields and TypeScript interface properties. Auto-converts snake_case/camelCase for comparison. Single-repo; cross-repo planned for roam ws api-drift | | roam codeowners [--unowned] [--owner NAME] | CODEOWNERS coverage analysis: owned/unowned files, top owners, and ownership risk | | roam drift [--threshold N] | Ownership drift detection: declared ownership vs observed maintenance activity | | roam suggest-reviewers [REV_RANGE] | Reviewer recommendation via ownership, recency, breadth, and impact signals | | roam simulate-departure <developer> | Knowledge-loss simulation: what breaks if a key contributor leaves | | roam dev-profile [--developer NAME] [--since N] | Developer productivity profile: commit patterns, specialization, impact, and knowledge concentration per contributor | | roam secrets [--fail-on-found] [--include-tests] | Secret scanning with masking, entropy detection, env-var suppression, remediation suggestions, and optional CI gate failure | | roam vulns [--import-file F] [--reachable-only] | Vulnerability scanning: ingest npm/pip/trivy/osv reports, auto-detect format, reachability filtering, SARIF output | | roam path-coverage [--from P] [--to P] [--max-depth N] | Find critical call paths (entry -> sink) with zero test protection. Suggests optimal test insertion points | | roam capsule [--redact-paths] [--no-signatures] [--output F] | Export sanitized structural graph (no code bodies) for external architectural review | | roam rules [--init] [--ci] [--rules-dir D] | Plugin DSL for governance: user-defined path/symbol/AST rules via .roam/rules/ YAML ($METAVAR captures supported) | | roam check-rules [--severity S] [--fix] | Evaluate built-in and user-defined governance rules (10 built-in: no-circular-imports, max-fan-out, etc.) | | roam vuln-map --generic\|--npm-audit\|--trivy F | Ingest vulnerability reports and match to codebase symbols | | roam vuln-reach [--cve C] [--from E] | Vulnerability reachability: exact paths from entry points to vulnerable calls | | roam supply-chain [--top N] | Dependency risk dashboard: pin coverage, risk scoring, supply-chain health | | roam sbom [--format cyclonedx\|spdx] [--no-reachability] [-o FILE] | SBOM generation (CycloneDX 1.5 / SPDX 2.3) enriched with call-graph reachability per dependency | | roam congestion [--window N] [--min-authors N] | Developer congestion detection: concurrent authors per file, coordination risk scoring | | roam invariants [--staged] [--range R] | Discover architectural contracts (invariants) from the codebase structure |

Multi-Repo Workspace

| Command | Description | |---------|-------------| | roam ws init <repo1> <repo2> [--name NAME] | Initialize a workspace from sibling repos. Auto-detects frontend/backend roles | | roam ws status | Show workspace repos, index ages, cross-repo edge count | | roam ws resolve | Scan for REST API endpoints and match frontend calls to backend routes | | roam ws understand | Unified workspace overview: per-repo stats + cross-repo connections | | roam ws health | Workspace-wide health report with cross-repo coupling assessment | | roam ws context <symbol> | Cross-repo augmented context: find a symbol across repos + show API callers | | roam ws trace <source> <target> | Trace cross-repo paths via API edges |

Global Options

| Option | Description | |--------|-------------| | roam --json <command> | Structured JSON output with consistent envelope | | roam --compact <command> | Token-efficient output: TSV tables, minimal JSON envelope | | roam --sarif <command> | SARIF 2.1.0 output for dead, health, complexity, rules, secrets, algo, py-types, py-modern (GitHub/CI integration) | | roam health --gate | CI quality gate. Reads .roam-gates.yml thresholds. Exit code 5 on failure |

Walkthrough: Investigating a Code