roam-code

The architectural intelligence layer for AI coding agents. Structural graph, architecture governance, multi-agent orchestration, vulnerability mapping, runtime analysis -- one CLI, zero API keys.

140 commands · 102 MCP tools · 27 languages · 100% local

---

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 ──> 139 Commands ──> AI Agent
              │              │                  │
           tree-sitter    symbols            comprehend
           27 languages   + edges            govern
           git history    + metrics          refactor
           runtime traces + architecture     orchestrate

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: 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

The 5 core commands shown above cover ~80% of agent workflows. All 140 commands are organized into 7 categories.

Getting Started

| Command | Description | |---------|-------------| | roam index [--force] [--verbose] | Build or rebuild the codebase index | | 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] [--semantic-backend MODE] | Manage .roam/config.json (DB path, excludes, optional ONNX semantic settings) | | 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 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] | Per-function cognitive complexity (SonarSource-compatible, triangular nesting penalty) + Halstead metrics (volume, difficulty, effort, bugs) + cyclomatic density | | 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] | Architectural fitness functions from .roam/fitness.yaml | | 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 | | 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, and algo (GitHub/CI integration) | | roam health --gate | CI quality gate. Reads .roam-gates.yml thresholds. Exit code 5 on failure |

Walkthrough: Investigating a Codebase

Here's how you'd use Roam to understand a project you've never seen before. Using Flask as an example:

Step 1: Onboard and get the full picture

$ roam init
Created .roam/fitness.yaml (6 starter rules)
Created .github/workflows/roam.yml
Done. 226 files, 1132 symbols, 233 edges.
Health: 78/100

$ roam understand
Tech stack: Python (flask, jinja2, werkzeug)
Architecture: Monolithic — 3 layers, 5 clusters
Key abstractions: Flask, Blueprint, Request, Response
Health: 78/100 — 1 god component (Flask)
Entry points: src/flask/__init__.py, src/flask/cli.py
Conventions: snake_case functions, PascalCase classes, relative imports
Complexity: avg 4.2, 3 high (>15), 0 critical (>25)

Step 2: Drill into a key file

$ roam file src/flask/app.py
src/flask/app.py  (python, 963 lines)

  cls  Flask(App)                                   :76-963
    meth  __init__(self, import_name, ...)           :152
    meth  route(self, rule, **options)               :411
    meth  register_blueprint(self, blueprint, ...)   :580
    meth  make_response(self, rv)                    :742
    ...12 more methods

Step 3: Who depends on this?

$ roam deps src/flask/app.py
Imported by:
file                        symbols
--------------------------  -------
src/flask/__init__.py       3
src/flask/testing.py        2
tests/test_basic.py         1
...18 files total

Step 4: Find the hotspots

$ roam weather
=== Hotspots (churn x complexity) ===
Score  Churn  Complexity  Path                    Lang
-----  -----  ----------  ----------------------  ------
18420  460    40.0        src/flask/app.py        python
12180  348    35.0        src/flask/blueprints.py python

Step 5: Check architecture health

$ roam health
Health: 78/100
  Tangle: 0.0% (0/1132 symbols in cycles)
  1 god component (Flask, degree 47, actionable)
  0 bottlenecks, 0 layer violations

=== God Components (degree > 20) ===
Sev      Name   Kind  Degree  Cat  File
-------  -----  ----  ------  ---  ------------------
WARNING  Flask  cls   47      act  src/flask/app.py

Step 6: Get AI-ready context for a symbol

$ roam context Flask
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

Callers: 47  Callees: 3

Step 7: Pre-change safety check

$ roam preflight Flask
=== Preflight: Flask ===
Blast radius: 47 callers, 89 transitive
Affected tests: 31 (DIRECT: 12, TRANSITIVE: 19)
Complexity: cc=40 (critical), nesting=6
Coupling: 3 hidden co-change partners
Fitness: 1 violation (max-complexity exceeded)
Verdict: HIGH RISK — consider splitting before modifying

Step 8: Decompose a large file

$ roam split src/flask/app.py
=== Split analysis: src/flask/app.py ===
  87 symbols, 42 internal edges, 95 external edges
  Cross-group coupling: 18%

  Group 1 (routing) — 12 symbols, isolation: 83% [extractable]
    meth  route              L411  PR=0.0088
    meth  add_url_rule       L450  PR=0.0045
    ...

=== Extraction Suggestions ===
  Extract 'routing' group: route, add_url_rule, endpoint (+9 more)
    83% isolated, only 3 edges to other groups

Step 9: Understand why a symbol matters

$ roam why Flask url_for Blueprint
Symbol     Role          Fan         Reach     Risk      Verdict
---------  ------------  ----------  --------  --------  --------------------------------------------------
Flask      Hub           fan-in:47   reach:89  CRITICAL  God symbol (47 in, 12 out). Consider splitting.
url_for    Core utility  fan-in:31   reach:45  HIGH      Widely used utility (31 callers). Stable interface.
Blueprint  Bridge        fan-in:18   reach:34  moderate  Coupling point between clusters.

Step 10: Generate docs and set up CI

$ roam describe --write
Wrote CLAUDE.md (98 lines)  # auto-detects: CLAUDE.md, AGENTS.md, .cursor/rules, etc.

$ roam health --gate
Health: 78/100 — PASS

Ten commands. Complete picture: structure, dependencies, hotspots, health, context, safety checks, decomposition, and CI gates.

Integration with AI Coding Tools

Roam is designed to be called by coding agents via shell commands. Instead of repeatedly grepping and reading files, the agent runs one roam command and gets structured output.

Decision order for agents:

| Situation | Command | |-----------|---------| | First time in a repo | roam understand then roam tour | | Need to modify a symbol | roam preflight <name> (blast radius + tests + fitness) | | Debugging a failure | roam diagnose <name> (root cause ranking) | | Need files to read | roam context <name> (files + line ranges) | | Need to find a symbol | roam search <pattern> | | Need file structure | roam file <path> | | Pre-PR check | roam pr-risk HEAD~3..HEAD | | What breaks if I change X? | roam impact <symbol> | | Check for N+1 queries | roam n1 (implicit lazy-load detection) | | Check auth coverage | roam auth-gaps (routes + controllers) | | Check migration safety | roam migration-safety (idempotency guards) |

Fastest setup:

roam describe --write               # auto-detects your agent's config file
roam describe --write -o AGENTS.md  # or specify an explicit path
roam describe --agent-prompt        # compact ~500-token prompt (append to any config)
roam minimap --update               # inject/refresh annotated codebase minimap in CLAUDE.md

Agent not using Roam correctly? If your agent is ignoring Roam and falling back to grep/read exploration, it likely doesn't have the instructions. Run:

roam describe --write          # writes instructions to your agent's config (CLAUDE.md, AGENTS.md, etc.)

If you already have a config file and don't want to overwrite it:

roam describe --agent-prompt   # prints a compact prompt — copy-paste into your existing config
roam minimap --update          # injects an annotated codebase snapshot into CLAUDE.md (won't touch other content)

This teaches the agent which Roam command to use for each situation (e.g., roam preflight before changes, roam context for files to read, roam diagnose for debugging).

## Codebase navigation

This project uses `roam` for codebase comprehension. Always prefer roam over Glob/Grep/Read exploration.

Before modifying any code:
1. First time in the repo: `roam understand` then `roam tour`
2. Find a symbol: `roam search <pattern>`
3. Before changing a symbol: `roam preflight <name>` (blast radius + tests + fitness)
4. Need files to read: `roam context <name>` (files + line ranges, prioritized)
5. Debugging a failure: `roam diagnose <name>` (root cause ranking)
6. After making changes: `roam diff` (blast radius of uncommitted changes)

Additional: `roam health` (0-100 score), `roam impact <name>` (what breaks),
`roam pr-risk` (PR risk), `roam file <path>` (file skeleton).

Run `roam --help` for all commands. Use `roam --json <cmd>` for structured output.

| 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 |

| Task | Use Roam | Use native tools | |------|----------|-----------------| | "What calls this function?" | roam symbol <name> | LSP / Grep | | "What files do I need to read?" | roam context <name> | Manual tracing (5+ calls) | | "Is it safe to change X?" | roam preflight <name> | Multiple manual checks | | "Show me this file's structure" | roam file <path> | Read the file directly | | "Understand project architecture" | roam understand | Manual exploration | | "What breaks if I change X?" | roam impact <symbol> | No direct equivalent | | "What tests to run?" | roam affected-tests <name> | Grep for imports (misses indirect) | | "What's causing this bug?" | roam diagnose <name> | Manual call-chain tracing | | "Codebase health score for CI" | roam health --gate | No equivalent |

MCP Server

Roam includes a Model Context Protocol server for direct integration with tools that support MCP.

pip install "roam-code[mcp]"
roam mcp

102 tools, 10 resources, and 5 prompts are available in the full preset. Most tools are read-only index queries; side-effect tools are explicitly annotated.

MCP v2 highlights (v11):

• In-process MCP execution (no subprocess shell-out per call)
• Preset-based tool surfacing (core, review, refactor, debug, architecture, full)
• Compound tools that collapse multi-step exploration/review flows into one call
• Structured output schemas + tool annotations for safer planner behavior

Default preset: core (24 tools: 23 core + roam_expand_toolset meta-tool).

# Default
roam mcp

# Full toolset
ROAM_MCP_PRESET=full roam mcp

# Legacy compatibility (same as full preset)
ROAM_MCP_LITE=0 roam mcp

Core preset tools: roam_affected_tests, roam_batch_get, roam_batch_search, roam_complexity_report, roam_context, roam_dead_code, roam_deps, roam_diagnose, roam_diagnose_issue, roam_diff, roam_expand_toolset, roam_explore, roam_file_info, roam_health, roam_impact, roam_pr_risk, roam_preflight, roam_prepare_change, roam_review_change, roam_search_symbol, roam_syntax_check, roam_trace, roam_understand, roam_uses.

<detai