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 preflight <name>        # blast radius + tests + complexity + architecture rules
$ roam health                  # composite score (0-100)
$ roam diff                    # blast radius of uncommitted changes

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.

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 140 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 milliseconds (about 1000x on benchmarked paths).
• 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: