roam-code

The local codebase intelligence layer that lets AI coding agents earn the right to change code — and prove they did.

_{Credential-free · zero network egress · tamper-evident ChangeEvidence packets · Apache 2.0 · runs entirely on your machine}

_{238 commands · 224 MCP tools (57 in the default core preset) · 28 languages}

Why Roam is different

Cursor, Cody, Aider, and Windsurf are human-first IDE surfaces that log a session. Roam is an agent-first CLI surface that gates the change and emits proof. The moat is three properties no competitor combines today:

• Credential-free. No account, no API key, no cloud login. pip install and run.
• Zero network egress. Your source code never leaves the machine. Air-gapped repos work the same as cloud repos.
• Tamper-evident ChangeEvidence packets. Every AI-assisted change compiles into one portable evidence packet (HMAC-chained run ledger + signed Code Graph Attestation + signed PR bundle) that answers the eight evidence questions: who acted, what authority existed, what context was read, what changed, what could break, what policy applied, what verified it, who accepted risk. Cursor logs the run; Roam proves the change.

Underneath sits a SQLite-backed graph of symbols, calls, imports, architecture layers, git history, runtime traces, smells, clones, security flows, and algorithmic patterns across 28 languages. Agents and developers query the same local facts before a change, during review, and after the patch lands.

Install + first three commands

Ten minutes from pip install to a verdict on whether your next edit is safe.

pip install "roam-code[mcp]"          # 1. install with MCP server for Claude Code / Cursor / Continue
cd /path/to/your/repo
roam init                             # 2. index the repo into .roam/index.db (one-time, ~30s on most repos)
roam health                           # 3. composite 0-100 score: complexity, cycles, dark-matter coupling, dead code
roam preflight <symbol>               # 4. blast radius + tests + complexity + architecture rules before you edit

Requires Python 3.10+. pipx install roam-code and uv tool install roam-code work too. Drop [mcp] if you only want the CLI.

Want to see it before installing? docs/fresh-install-smoke.md is a verbatim transcript of these four commands run against a clean venv and a three-file synthetic project — copy-paste reproducible, no synthetic output.

What's next

Pick the path that matches your role:

• 5-minute demo (CTO/CISO/dev-tools-lead): The Canonical Demo — install → health → preflight → critique → signed ChangeEvidence packet, in five commands, without leaving the laptop. This is the screen-recording arc that establishes the moat in one sitting.
• Developer tutorial (15 min): Getting Started — install, index, query, ship.
• Agent integration: roam mcp-setup claude-code (or cursor, continue) — then see Using Roam via MCP for the cold-start envelope and canonical agent loop.
• Full surface reference: Command Reference — every command, every flag, every JSON envelope.
• Architecture deep-dive: Architecture — how the graph, findings registry, run ledger, and evidence compiler fit together.

What's New in v13

v13.2 (released 2026-05-16) -- Evidence freshness + resolution disclosure + public-surface cleanup

• Canonical unresolved-path envelopes across high-traffic commands. impact, preflight, trace, test-map, context, safe-delete, split, and why now use one explicit "not found" shape in JSON mode instead of mixing exit codes and partial-success vocabulary.
• Evidence freshness is now stamped at the producer. Runs record hashes for .roam-rules.yml, .roam/constitution.yml, and .roam/control-map.yml, so later evidence packets can prove which policy/config inputs were active.
• PR Replay evidence coverage improved. The replay path now answers 7 of the 8 evidence questions completely and marks the remaining approvals question as producer_not_available instead of silently omitting it.
• Public surface refreshed to the current shape. README, MCP metadata, and install guidance now describe the 238-command / 224-tool v13.2 surface with the 57-tool core preset.

v13.1 (released 2026-05-15) -- Pattern-2 propagation + shared YAML helper + 3 flagship silent-fallback seals

• 3 flagship Pattern-2 silent-fallback bugs sealed (W826/W834/W836). cmd_taint, cmd_health, and cmd_doctor now emit explicit state="empty_corpus" + partial_success=True on unanalyzed repos instead of false Healthy 100/100 / No taint findings / all checks passed verdicts. Security-critical for cmd_taint, CI-gate-critical for cmd_health --gate.
• Shared YAML config-loader helper. New src/roam/commands/_yaml_loader.py::load_yaml_with_warnings() absorbs the boilerplate Pattern-2 plumbing (PyYAML + tiny-parser + structured warnings + root-type check). 5 of 7 surveyed YAML loaders migrated. Net ~125 LOC removed across the package.
• 5 new live smell detectors. type-switch, speculative-generality, empty-catch, cross-layer-clone, and parallel-hierarchy bring the roam smells roster to 24 deterministic detectors. The rename-invariant clone work exists as clone-analysis groundwork, not a public roam smells --kind id yet.
• @detector registry consolidation (W941, Gate-1 closure). ALL_DETECTORS and _SMELL_KIND_TO_CONFIDENCE are derived views from the @detector-decorated registry. Parallel-maintenance debt class eliminated for smell detectors.
• Cargo-cult or "" cleanup (W1029/W1013/W1014/W1034). 14 defensive wrappers removed across cmd_complexity, cmd_fan, cmd_risk, cmd_fn_coupling, laws/miner, world_model/causal_graph, search/tfidf, search/index_embeddings. 3 helpers None-guarded at source.
• SQL LIKE ESCAPE discipline (W990–W993). 26 wildcard-unsafe LIKE patterns hardened across 4 files; drift-guard test enforces forever.
• Catalog/_shared.py hoisting. 6 helpers consolidated to a canonical home with __all__; 6 catalog/* modules adopted the __all__ discipline; cross-layer _is_test_path / _camel_split / _enclosing_symbol / _parse_iso / make_finding_id / make_smell_finding all single-sourced.
• 30+ behavioral Pattern-2 fixes across cmd_alerts / cmd_smells / cmd_pr_risk / cmd_taint / cmd_health / cmd_doctor / finding_suppress / smells_suppress / suppression / sarif.
• Empty-corpus smoke sweep (W805 + W639 + W661). 25+ detectors smoke-tested; 12 already clean, 7 auto-fixed by W817 helper-level auto-inject, 3 dedicated flagship fixes. Forbidden-fragment blacklist ("safe" / "healthy" / "100/100" / "no concerns") prevents regressions.
• No persisted-data breaks. Hash-stability mandate held: 31/31 test_evidence_schema_migration.py byte-identical; make_finding_id hashes confirmed byte-identical before/after consolidation.

v13.0 (released 2026-05-13) -- Agent-OS substrate + Laravel idioms + Vue SFC

• Agent-OS control plane. New repo-local substrates under .roam/: constitution (single source for laws / rules / memory / gates), HMAC-chained run ledger (roam runs start|verify|end), multi-agent leases (roam lease claim|release|list), portable agent memory (.roam/memory.jsonl), and 4 cumulative modes (read_only → safe_edit → migration → autonomous_pr). Mode enforcement is opt-in behind ROAM_MODE_ENFORCEMENT=1 for v13.0 (PR-C ready; staged rollout). See CLAUDE.md "Agent OS substrate" for the canonical loop.
• World-model classifiers (R28). 4 new detectors with first-class CLI surface: roam side-effects (io_read / io_write / mutation / process / none), roam idempotency (idempotent / non_idempotent / unknown), roam causal-graph (param → sink dependency edges), and roam tx-boundaries (begin / commit / rollback regions + unsafe_mutation outside-tx findings).
• Laravel dynamic-dispatch idioms. New src/roam/index/laravel_post.py post-resolver catches 7 of 8 implicit-edge idioms that auth-gaps, n1, and algo were silently missing: Route closures, Eloquent scopes, Policy resolution, Observer registration, Job dispatch, Queue worker dispatch, and Artisan commands.
• Vue SFC import graph. Single-File Component support (.vue) — template, script, and style blocks parsed into the symbol graph; imports + component registrations resolved across the SFC boundary so roam impact, roam context, and roam preflight work on Vue projects.
• Plugin substrate (R25) validated end-to-end. The roam-plugin-* entry-point surface (see CLAUDE.md "Writing a roam plugin") shipped clean cut on Rails Path A — framework-specific knowledge can ship as a plugin instead of landing in core.
• ~20 new CLI commands. roam brief, roam next, roam mode, roam constitution, roam laws, roam memory, roam lease, roam runs, roam replay, roam agent-score, roam agents-md, roam architecture-drift, roam graph-diff, roam side-effects, roam idempotency, roam causal-graph, roam tx-boundaries, roam batch-search, roam complete, roam mcp.
• Real-world feedback fixes. stale-refs heading-slugger now matches GitHub's algorithm exactly; stale-refs --fix URL-half + bare-backtick corruption guards; algo nested-lookup dataflow predicate + PHP ===/!== detection; auth-gaps helper indirection (2-level same-class + ancestor descent); over-fetch 3-state classification (BARE / GUARDED_RELATION / UNGUARDED_RELATION); pr-bundle --strict-resolved + --ci global mode integration.
• Schema bump (USER_VERSION 12 → 13). Migration #51 adds the loop_eq_with_dependent_write column that backs the new algo nested-lookup dataflow predicate.

Full release notes in CHANGELOG.md.

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).
• 211 CLI commands, 145 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). 57-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.
• 28 languages with 17 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 conflict-aware planning
• 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.

Evidence that never leaves your machine. Local SQLite, no telemetry, no network calls. Evidence packets hash-verify offline — 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.

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 v13 · 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.10+. 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
• Run the v2 stack on every PR: git diff | roam pr-analyze --explain (gates AI-generated risk; pair with roam pr-comment-render for sticky GitHub comments — see Roam Review)
• First-touch demo: roam dogfood (audit + pr-analyze + audit-trail + governance checks in one envelope)
• Add to CI: roam init already generated a GitHub Action
• Customer-facing artifacts: see starter rule packs at templates/rules/, the agent change packet at templates/examples/agent-change-packet.md, the audit-report template + redacted sample at templates/audit-report/, and the security/procurement packet at templates/legal/security-procurement-packet.md.

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 ~233 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 238 commands (231 canonical + 7 aliases) organised into 7 categories (aliases for muscle memory: algo → math, weather → churn, digest / snapshot / trend → trends, onboard → understand, refs → uses), but you don't need to know that to start.

Getting Started

Daily Workflow

Codebase Health

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:

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/ (267 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

Exploration

Reports & CI

Multi-Repo Workspace

Global Options

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:

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.

MCP Server

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

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

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

See Using Roam via MCP for the first-run flow, the cold-start envelope your agent will see on a fresh repo, and the canonical 7-step agent sequence.

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

MCP-native enhancements (v12):

• Sampling-driven compression -- pass summarize=True to roam_explore, roam_understand, roam_health, or roam_repo_map. The server asks the client's own LLM (no API keys) to compress the full envelope into a short briefing, dropping output from ~50 KB JSON to ~1-2 KB prose. Falls back gracefully when the client doesn't support sampling.
• Server-side session memory -- roam_context, roam_explore, and roam_retrieve now remember symbols you've touched in the current session and auto-bias ranking without you threading recent_symbols through every call. Explicit args still win.
• Phase-aware progress -- roam_init, roam_reindex, and roam_orchestrate stream real discover -> parse -> extract -> resolve -> graph -> metrics progress to the client, replacing the old 5/100 placeholders.
• Symbol & path completions -- new roam_complete(prefix, kind, limit) tool returns just names from the FTS5 index (cheaper than roam_search_symbol). A protocol-level handler is also installed for clients that support completion/complete.
• Reactive resource invalidation (opt-in) -- set ROAM_MCP_WATCH=1 and the server watches the working tree, runs incremental reindex on file changes, and emits notifications/resources/updated for roam://health, roam://summary, etc., so subscribed clients see fresh data without polling.

Default preset: core (58 tools: 57 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_alerts, roam_ask, roam_audit_trail_conformance_check, roam_audit_trail_export, roam_audit_trail_verify, roam_batch_get, roam_batch_search, roam_catalog, roam_complete, roam_complexity_report, roam_context, roam_critique, roam_dead_code, roam_deps, roam_diagnose, roam_diagnose_issue, roam_diff, roam_disambiguate, roam_dogfood, roam_explore, roam_fetch_handle, roam_file_info, roam_fleet_plan, roam_for_bug_fix, roam_for_new_feature, roam_for_refactor, roam_for_security_review, roam_health, roam_impact, roam_metrics_push, roam_oracle_is_clone_of, roam_oracle_is_reachable_from_entry, roam_oracle_is_test_only, roam_oracle_route_exists, roam_oracle_symbol_exists, roam_pr_analyze, roam_pr_comment_render, roam_pr_risk, roam_preflight, roam_prepare_change, roam_py_modern, roam_py_types, roam_retrieve, roam_review_change, roam_rules_validate, roam_search_symbol, roam_session_metrics, roam_syntax_check, roam_taint_classify, roam_test_impact, roam_timeline, roam_trace, roam_understand, roam_uses, roam_validate_plan, roam_why_fail.

New in v12.26: roam_pr_analyze, roam_pr_comment_render, roam_metrics_push, roam_audit_trail_verify, roam_audit_trail_export, roam_audit_trail_conformance_check, roam_rules_validate, roam_dogfood — Roam Review + Cloud engines + governance audit-trail toolkit + production-grade rules linting + one-shot v2 stack runner.

Resources: roam://health (current health score), roam://summary (project overview)

claude mcp add roam-code -- roam mcp

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "roam-code": {
      "command": "roam",
      "args": ["mcp"]
    }
  }
}

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "roam-code": {
      "command": "roam",
      "args": ["mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "roam-code": {
      "command": "roam",
      "args": ["mcp"]
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "roam-code": {
      "type": "stdio",
      "command": "roam",
      "args": ["mcp"]
    }
  }
}

Roam Review (PR bot for AI-generated changes)

Status (2026-05-09): Early access. Pricing published, sign-up via hello@roam-code.com. Flat tiers from $99/mo: Starter $99 · Team $299 · Business $799 · Scale $1,499. Free for open-source forever. Full pricing at https://roam-code.com/pricing.

Most "AI safety net" tools — CodeRabbit, Greptile, Qodo — review PR semantics (does the diff look right?). They don't read your graph: who calls the changed symbol, which layer it belongs to, whether the AI just touched a god-component with 47 callers. Roam Review fills that gap.

roam pr-analyze is the CLI engine: pipe a unified diff in, get back a verdict (INTENTIONAL / SAFE / REVIEW / BLOCK) plus AI-likelihood score, blast radius, rule violations, suggested reviewers, and a governance audit-trail record.

git diff main..HEAD | roam pr-analyze --explain --with-reviewers --audit-trail
roam pr-analyze main..HEAD --gate                      # exit 5 on BLOCK (CI gate)
roam --json pr-analyze --input pr.diff | roam pr-comment-render   # ready-to-post markdown
roam pr-analyze --batch ./diffs/ --cache --parallel 4  # 24-55x speedup on incremental re-runs
roam audit-trail-verify                                # check SHA-256 chain integrity
roam audit-trail-conformance-check --gate              # governance-evidence score (CI)

Nine weighted heuristic signals score the diff for AI-likelihood: add/remove ratio, comment density, test coverage, function-size variance, generic naming, orphan imports, placeholder density (TODO/FIXME/NotImplementedError stubs), LLM-phrase density ("we use this approach because…"), suspicious imports (numbered modules, mass typing imports). Each carries language-aware weights across Python / TypeScript / JavaScript / Go / Rust / Java / Kotlin. Starter rule packs ship for Python, TypeScript, Go, and Java at templates/rules/ — drop one at .roam/rules.yml to enable. Custom rules look like:

rules:
  - id: no-frontend-db-import
    description: Frontend modules must not import from db/ directly
    pattern: import_from              # supported: import_from, function_call, class_inherit, decorator_use
    source_glob: "frontend/**/*.{ts,tsx}"
    forbidden_target_glob: "lib/db/**"
    severity: BLOCK
  - id: no-eval
    pattern: function_call
    source_glob: "src/**/*.py"
    forbidden_target_glob: "eval"
    severity: BLOCK

A drift baseline (--save-baseline / --baseline FILE) compares the current PR's signals against the previous analysis and auto-escalates the verdict on regression — the GitHub App reads this to render (+5 vs prev) / (-22 vs prev) arrows on every push.

The pr-analyze --audit-trail flag appends a SHA-256-chained record to .roam/audit-trail.jsonl for each analysis (actor, repo, git SHA, diff hash, verdict, blast radius, AI-likelihood, intent marker). roam audit-trail-verify walks the chain and surfaces tampered records; roam audit-trail-export --format md|csv|json produces procurement-friendly reports. This is best framed as SOC 2 CC8.1, ISO 42001, and internal AI-governance evidence. Article 12 is only relevant for actual Annex III high-risk AI-system buyers, and Roam's records are supporting evidence rather than complete runtime inference logs.

A hosted GitHub App is in development on top of this CLI engine. Until it ships, the CLI is usable today as a free CI gate (roam pr-analyze --gate exits 5 on BLOCK).

Roam Cloud (metrics history, no source upload)

Status (2026-05-09): Early access. From $19/repo/mo (Starter), $99/mo Team (10 repos), $299/mo Growth. 30-day money-back. Source code is never uploaded — only metrics.

roam metrics-push sends a summary-only payload from roam audit --json to a Roam Cloud endpoint — numerical metrics, file paths (or SHA-256 hashes when --anonymize), and identifier names only. No source-code bodies are transmitted, ever. Inspect the exact payload locally with --dry-run before any token is set.

roam metrics-push --dry-run                            # local-only inspection
roam metrics-push --token $ROAM_CLOUD_TOKEN --anonymize
roam metrics-push --no-hotspots --json                 # minimal payload

The hosted dashboard at roam.cloud (in development) renders trend charts of health-score, debt, dead-code count, danger-zone count, and bus-factor concentration over time. The schema (roam-metrics-v1) is allow-listed: any payload key outside the allow-list is rejected by the receiving API.

Both products are paid layers on top of the free CLI; the CLI itself stays Apache 2.0, zero-API-key, fully local, forever.

PR Replay (one-shot paid audit)

Status (2026-05-09): Available today via email. Self-serve checkout launches alongside Roam Review.

PR Replay runs Roam against your last 30 or 90 merged PRs and ships a written structural-review report plus a founder walk-through. Same engine as the free CLI; the engagement is the report + the call.

Order paid tiers by emailing hello@roam-code.com — the self-serve Stripe checkout launches with Roam Review. Full deliverable shape at https://roam-code.com/audit.

CI/CD Integration

All you need is Python 3.10+ and pip install roam-code.

GitHub Actions

# .github/workflows/roam.yml
name: Roam Analysis
on: [pull_request]

jobs:
  roam:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: Cranot/roam-code@main
        with:
          commands: health
          gate: "score>=70"
          sarif: true
          comment: true

Use roam init to auto-generate this workflow.

roam-analysis:
  stage: test
  image: python:3.12-slim
  before_script:
    - pip install roam-code
  script:
    - roam index
    - roam health --gate
    - roam --json pr-risk origin/main..HEAD > roam-report.json
  artifacts:
    paths:
      - roam-report.json
  rules:
    - if: $CI_MERGE_REQUEST_IID

Universal pattern:

pip install roam-code
roam index
roam health --gate               # exit 5 on failure (reads .roam-gates.yml)
roam --json health > report.json

SARIF Output

Roam exports analysis results in SARIF 2.1.0 format for GitHub Code Scanning.

Fourteen commands honour the global --sarif flag (the authoritative list is _SARIF_CONSUMERS in src/roam/cli.py, drift-guarded by tests/test_sarif_consumer_list.py). Minimal end-to-end upload:

- run: roam --sarif health > roam-health.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: roam-health.sarif

For the full CI integration playbook -- plain-pip quickstart, composite Action, GitLab/Jenkins/Azure/BitBucket templates, severity gates, and upload guardrails -- see docs/ci-integration.md.

Programmatic access from Python:

from roam.output.sarif import health_to_sarif, write_sarif

sarif = health_to_sarif(health_data)
write_sarif(sarif, "roam-health.sarif")

For Teams

Zero infrastructure, zero vendor lock-in, zero data leaving your network.

Week 1-2 (pilot): 1-2 developers run roam init on one repo. Use roam preflight before changes, roam pr-risk before PRs.

Week 3-4 (expand): Add roam health --gate to CI as a non-blocking check (configure thresholds in .roam-gates.yml).

Month 2+ (standardize): Tighten gate thresholds. Expand to additional repos. Track trajectory with roam trends.

Language Support

Tier 1 -- Full extraction (dedicated parsers)

Cross-language edges mean roam impact AccountService shows blast radius across Apex, LWC, Aura, Visualforce, and Flows.

| Ruby | .rb | classes, modules, methods, singleton methods, constants | require, require_relative, include/extend, calls, ClassName.new | class inheritance | | Kotlin | .kt .kts | classes, interfaces, enums, objects, functions, methods, properties | imports, calls, type refs | extends, implements | | Scala | .scala .sc | classes, traits, objects, case classes, functions, methods, val/var, type aliases | imports, calls, new | extends, with (trait mixins) | | SQL (DDL) | .sql | tables, columns, views, functions, triggers, schemas, types (enums), sequences | foreign keys, view table deps, trigger table/function refs | -- | | Swift | .swift | classes, structs, enums, protocols, functions, methods, properties | imports, calls, type refs | extends, conforms | | Dart | .dart | classes, mixins, extensions, enums, type aliases, functions, methods, constructors | imports, calls, type refs | extends, implements, with | | JSONC | .jsonc | via JSON grammar | -- | -- | | MDX | .mdx | via Markdown grammar | -- | -- |

Performance

Indexing Speed

Quality Benchmark

Token Efficiency

Agent-efficiency benchmarks: see the benchmarks/ directory for harness, repos, and results.

How It Works

Codebase
    |
[1] Discovery ──── git ls-files (respects .gitignore + .roamignore)
    |
[2] Parse ──────── tree-sitter AST per file (28 languages)
    |
[3] Extract ────── symbols + references (calls, imports, inheritance)
    |
[4] Resolve ────── match references to definitions → edges
    |
[5] Metrics ────── adaptive PageRank, betweenness, cognitive complexity, Halstead
    |
[6] Algorithms ── 23-pattern anti-pattern catalog (O(n^2) loops, N+1, recursion)
    |
[7] Git ────────── churn, co-change matrix, authorship, Renyi entropy
    |
[8] Clusters ───── Louvain community detection
    |
[9] Health ─────── per-file scores (7-factor) + composite score (0-100)
    |
[10] Store ─────── .roam/index.db (SQLite, WAL mode)

After the first full index, roam index only re-processes changed files (mtime + SHA-256 hash). Incremental updates are near-instant.

.roamignore

Create a .roamignore file in your project root to exclude files from indexing. It uses full gitignore syntax:

Key rules: * matches within a single path segment (not across /). ** matches across / boundaries. Last matching pattern wins (for negation). Patterns containing / are anchored to the repo root.

# .roamignore example
*_pb2.py
*_pb2_grpc.py
vendor/
node_modules/
*.generated.*
/build/
!build/keep/

You can also exclude patterns via roam config --exclude "*.proto" (stored in .roam/config.json) or inspect active patterns with roam config --show.

• Adaptive PageRank -- damping factor auto-tunes based on cycle density (0.82-0.92); identifies the most important symbols (used by map, search, context)
• Personalized PageRank -- distance-weighted blast radius for impact (Gleich, 2015)
• Adaptive betweenness centrality -- exact for small graphs, sqrt-scaled sampling for large (Brandes & Pich, 2007); finds bottleneck symbols
• Edge betweenness centrality -- identifies critical cycle-breaking edges in SCCs (Brandes, 2001)
• Tarjan's SCC -- detects dependency cycles with tangle ratio
• Propagation Cost -- fraction of system affected by any change, via transitive closure (MacCormack, Rusnak & Baldwin, 2006)
• Algebraic connectivity (Fiedler value) -- second-smallest Laplacian eigenvalue; measures architectural robustness (Fiedler, 1973)
• Louvain community detection -- groups related symbols into clusters
• Modularity Q-score -- measures if cluster boundaries match natural community structure (Newman, 2004)
• Conductance -- per-cluster boundary tightness: cut(S, S_bar) / min(vol(S), vol(S_bar)) (Yang & Leskovec)
• Topological sort -- computes dependency layers, Gini coefficient for layer balance (Gini, 1912), weighted violation severity
• k-shortest simple paths -- traces dependency paths with coupling strength
• Renyi entropy (order 2) -- measures co-change distribution; more robust to outliers than Shannon (Renyi, 1961)
• Mann-Kendall trend test -- non-parametric degradation detection, robust to noise (Mann, 1945; Kendall, 1975)
• Sen's slope estimator -- robust trend magnitude, resistant to outliers (Sen, 1968)
• NPMI -- Normalized Pointwise Mutual Information for coupling strength (Bouma, 2009)
• Lift -- association rule mining metric for co-change statistical significance (Agrawal & Srikant, 1994)
• Halstead metrics -- volume, difficulty, effort, and predicted bugs from operator/operand counts (Halstead, 1977)
• SQALE remediation cost -- time-to-fix estimates per issue type for tech debt prioritization (Letouzey, 2012)
• Algorithm anti-pattern catalog -- 23 patterns detecting suboptimal algorithms (quadratic loops, N+1 queries, quadratic string building, branching recursion, manual top-k, loop-invariant calls) with confidence calibration via caller-count and bounded-loop analysis

Composite health score (0-100) using a weighted geometric mean of sigmoid health factors. Non-compensatory: a zero in any dimension cannot be masked by high scores in others.

Each factor uses sigmoid health: h = e^(-signal/scale) (1 = pristine, approaches 0 = worst). Score = 100 * product(h_i ^ w_i). Also reports propagation cost (MacCormack 2006) and algebraic connectivity (Fiedler 1973). Per-file health (1-10) combines: cognitive complexity (triangular nesting penalty per Sweller's Cognitive Load Theory), indentation complexity, cycle membership, god component membership, dead export ratio, co-change entropy, and churn amplification.

How Roam Compares

roam-code is the only tool that combines graph algorithms (PageRank, Tarjan SCC, Louvain clustering), git archaeology, architecture simulation, and multi-agent partitioning in a single local CLI with zero API keys.

Documentation lives at https://roam-code.com/docs/:

• Tutorial — https://roam-code.com/docs/getting-started
• Command reference — https://roam-code.com/docs/command-reference
• Architecture guide — https://roam-code.com/docs/architecture
• Integration tutorials — https://roam-code.com/docs/integration-tutorials

Key Differentiators

• vs AI IDEs (Cursor, Windsurf, Augment): roam-code provides deterministic structural analysis. AI IDEs use probabilistic embeddings that can't guarantee reproducible results.
• vs AI Agents (Claude Code, Codex CLI, Gemini CLI): These agents read files one at a time. roam-code pre-computes relationships so agents get instant answers about architecture, blast radius, and dependencies.
• vs SAST Tools (SonarQube, CodeQL, Semgrep): SAST tools find bugs and vulnerabilities. roam-code understands architecture -- how code is structured, where it's coupled, and what breaks when you change it. Complementary, not competitive.
• vs Code Search (Sourcegraph/Amp, Greptile): Text search finds where code is. roam-code understands why code matters -- which functions are central, which modules are tangled, which files are high-risk.

FAQ

Does Roam send any data externally? No. Zero network calls. No telemetry, no analytics, no update checks.

Can Roam run in air-gapped environments? Yes. Once installed, no internet access is required.

Does Roam modify my source code? Read-only by default. Creates .roam/ with an index database. The roam mutate command can apply code changes (move/rename/extract) but defaults to --dry-run mode — you must explicitly pass --apply to write changes.

How does Roam handle monorepos? Indexes from the root. Batched SQL handles 100k+ symbols. Incremental updates stay fast.

How does Roam handle multi-repo projects (e.g., frontend + backend)? Use roam ws init <repo1> <repo2> to create a workspace. Each repo keeps its own index; a workspace overlay DB stores cross-repo API edges. roam ws resolve scans for REST endpoints and matches frontend calls to backend routes. Then roam ws context, roam ws trace, etc. work across repos.

Is Roam compatible with SonarQube / CodeScene? Yes. Roam complements existing tools. Both can run in the same CI pipeline. SARIF output integrates with GitHub Code Scanning.

Limitations

Static analysis trade-offs:

• Static analysis primarily -- can't trace dynamic dispatch, reflection, or eval'd code. Runtime trace ingestion (roam ingest-trace) adds production data but requires external trace export
• Import resolution is heuristic -- complex re-exports or conditional imports may not resolve
• Limited cross-language edges -- Salesforce, Protobuf, REST API, and multi-repo edges are supported, but not arbitrary FFI
• Tier 2 languages get basic symbol extraction only via generic tree-sitter walker
• Large monorepos (100k+ files) may have slow initial indexing

Troubleshooting

Update / Uninstall

# Update
pipx upgrade roam-code
uv tool upgrade roam-code
pip install --upgrade roam-code

# Uninstall
pipx uninstall roam-code
uv tool uninstall roam-code
pip uninstall roam-code

Delete .roam/ from your project root to clean up local data.

Development

git clone https://github.com/Cranot/roam-code.git
cd roam-code
pip install -e ".[dev]"   # includes pytest, ruff
pytest tests/              # ~7,500 tests, Python 3.10-3.13

# Or use Make targets:
make dev      # install with dev extras
make test     # run tests
make lint     # ruff check

roam-code/
├── pyproject.toml
├── action.yml                         # Reusable GitHub Action
├── src/roam/
│   ├── __init__.py                    # Version (from pyproject.toml)
│   ├── cli.py                         # Click CLI (231 canonical + 7 aliases)
│   ├── mcp_server.py                  # MCP server (224 tools, 10 resources, 6 prompts)
│   ├── db/
│   │   ├── connection.py              # SQLite (WAL, pragmas, batched IN)
│   │   ├── schema.py                  # Tables, indexes, migrations
│   │   └── queries.py                 # Named SQL constants
│   ├── index/
│   │   ├── indexer.py                 # Orchestrates full pipeline
│   │   ├── discovery.py               # git ls-files, .gitignore
│   │   ├── parser.py                  # Tree-sitter parsing
│   │   ├── symbols.py                 # Symbol + reference extraction
│   │   ├── relations.py               # Reference resolution -> edges
│   │   ├── complexity.py              # Cognitive complexity (SonarSource) + Halstead metrics
│   │   ├── git_stats.py               # Churn, co-change, blame, Renyi entropy
│   │   ├── incremental.py             # mtime + hash change detection
│   │   ├── file_roles.py              # Smart file role classifier
│   │   └── test_conventions.py        # Pluggable test naming adapters
│   ├── languages/
│   │   ├── base.py                    # Abstract LanguageExtractor
│   │   ├── registry.py                # Language detection + aliasing
│   │   ├── *_lang.py                  # One file per language (21 dedicated + generic)
│   │   └── generic_lang.py            # Tier 2 fallback
│   ├── bridges/
│   │   ├── base.py, registry.py       # Cross-language bridge framework
│   │   ├── bridge_salesforce.py       # Apex <-> Aura/LWC/Visualforce
│   │   └── bridge_protobuf.py         # .proto -> Go/Java/Python stubs
│   ├── catalog/
│   │   ├── tasks.py                  # Universal algorithm catalog (23 patterns)
│   │   └── detectors.py              # Anti-pattern detectors with confidence calibration
│   ├── workspace/
│   │   ├── config.py                  # .roam-workspace.json
│   │   ├── db.py                      # Workspace overlay DB
│   │   ├── api_scanner.py             # REST API endpoint detection
│   │   └── aggregator.py              # Cross-repo aggregation
│   ├── graph/
│   │   ├── builder.py, pagerank.py    # DB -> NetworkX, PageRank
│   │   ├── cycles.py, clusters.py     # Tarjan SCC, propagation cost, Louvain, modularity Q
│   │   ├── layers.py, pathfinding.py  # Topo layers, k-shortest paths
│   │   ├── simulate.py, spectral.py   # Architecture simulation, Fiedler bisection
│   │   ├── partition.py, fingerprint.py # Multi-agent partitioning, topology fingerprints
│   │   └── anomaly.py                 # Statistical anomaly detection
│   ├── commands/
│   │   ├── resolve.py                 # Shared symbol resolution
│   │   ├── graph_helpers.py           # Shared graph utilities (adj builders, BFS)
│   │   ├── context_helpers.py         # Data-gathering helpers for context command
│   │   ├── gate_presets.py            # Framework-specific gate rules
│   │   └── cmd_*.py                   # One module per command
│   ├── analysis/
│   │   ├── effects.py                 # Side-effect classification engine
│   │   └── taint.py                   # Taint analysis
│   ├── refactor/
│   │   ├── codegen.py                 # Import generation (Python/JS/Go)
│   │   └── transforms.py             # move/rename/add-call/extract transforms
│   ├── rules/
│   │   ├── engine.py                  # YAML rule parser + graph query evaluator
│   │   ├── builtin.py                 # 10 built-in governance rules
│   │   ├── ast_match.py               # AST pattern matching with $METAVAR captures
│   │   └── dataflow.py                # Intra-procedural dataflow analysis
│   ├── runtime/
│   │   ├── trace_ingest.py            # OpenTelemetry/Jaeger/Zipkin ingestion
│   │   └── hotspots.py                # Runtime hotspot analysis
│   ├── search/
│   │   ├── tfidf.py                   # TF-IDF semantic search engine
│   │   ├── index_embeddings.py        # Embedding index builder
│   │   └── onnx_embeddings.py         # Optional local ONNX semantic backend
│   ├── security/
│   │   ├── vuln_store.py              # CVE/vulnerability storage
│   │   └── vuln_reach.py              # Vulnerability reachability paths
│   └── output/
│       ├── formatter.py               # Token-efficient formatting
│       ├── sarif.py                   # SARIF 2.1.0 output
│       └── schema_registry.py         # JSON envelope schema versioning
└── tests/                             # ~7,500 tests across 267 test files

Dependencies

Optional: fastmcp >= 2.0 (MCP server — install with pip install "roam-code[mcp]")

Optional: Local semantic ONNX stack (numpy, onnxruntime, tokenizers) via pip install "roam-code[semantic]"; verify activation with roam config --semantic-status.

Contributing

git clone https://github.com/Cranot/roam-code.git
cd roam-code
pip install -e .
pytest tests/   # all ~7,500 tests must pass

Good first contributions: add a Tier 1 language (see go_lang.py or php_lang.py as templates), improve reference resolution, add benchmark repos, extend SARIF converters, add MCP tools.

Please open an issue first to discuss larger changes.

License

Apache 2.0