cranot/roam-code

---

Jump to — Why Roam · Install · The Compiler · Core commands · MCP server · AI-tool integration · Roam Guard (PR gate) · Performance · Compare · Pricing · FAQ

---

Why Roam is different

METR and FrontierCode both point at the same gap: passing tests is not the same as mergeable code. Roam is an agent-first CLI surface that gives the agent local graph facts before it edits, gates risky changes, and emits scoped evidence after the run. In the agent/review tools surveyed as of 2026-06-12, the differentiator is this combination:

• Credential-free. No account, no API key, no cloud login. pip install and run.
• 100% local by default. Source code never leaves the machine; air-gapped repos work like cloud repos. The single outbound surface (roam metrics-push) is opt-in, summary-only, and prints its exact payload under --dry-run.
• Tamper-evident ChangeEvidence packets. A Roam-guided change can compile into one portable packet — HMAC-chained run ledger + signed Code Graph Attestation + signed PR bundle — answering eight questions: who acted, what authority existed, what context was read, what changed, what could break, what policy applied, what verified it, who accepted risk. PR Replay maps those eight questions today: structural change/risk/policy axes are in scope, context and verification are partial, and missing identity/authority/approval evidence is disclosed instead of invented. Cursor logs the run; Roam records and verifies the evidence its producers captured.
• MCP runtime security at the wrapper boundary. Every MCP response is scrubbed for secrets on egress, gated against the active mode (read_only / safe_edit / migration / autonomous_pr) with a closed-enum policy_decision, and each decision receipt is HMAC-linked into the signed run ledger. Inside-server controls; the gateway layer (Interlock / Lasso / Portkey) composes on top — see dev/MCP-SECURITY-POSTURE.md.

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

Dependency-aware, not string-based. Roam knows Flask has 47 dependents and 31 affected tests; grep knows it appears 847 times. One command replaces 5-10 tool calls — <0.5s per query, plain-ASCII output, --json and --sarif envelopes for agents and CI.

Illustrative — a typical agent workflow on a 200-file Python project (Flask). Reproducible smoke transcript in docs/fresh-install-smoke.md; full indexing-rate harness in benchmarks/. Exact numbers vary with repo size, agent prompt, and model.

---

Install + first four commands

About two 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                # 4. blast radius + tests + complexity + architecture rules before you edit

Python 3.10+. pipx install roam-code and uv tool install roam-code work too. Drop [mcp] for CLI-only. See docs/fresh-install-smoke.md for a verbatim transcript of these four commands against a clean venv.

Step 4 is the payoff — roam preflight on a hot symbol returns a verdict before you touch it:

$ roam preflight open_db
VERDICT: Significant risk — CRITICAL, 1847 symbols in blast radius

Pre-flight check for `open_db (src/roam/db/connection.py:799)`:

  Blast radius:     1847 symbols in 382 files                [CRITICAL]
  Affected tests:   617 direct, 962 transitive               [OK]
  Complexity:       cc=30, nest=4                            [CRITICAL]
  Coupling:         2 files often change together            [MEDIUM]
  Conventions:      no violations                            [OK]

  Overall risk: CRITICAL
  Risk driver:  complexity (cc=30, CRITICAL)

An agent sees the blast radius before it edits — not after the tests fail.

---

The Compiler — your agent’s first token already knows the answer

You ask your agent “who calls handleSave?” and watch it grep, open three files, grep again, read a fourth — six turns and $1.30 later you get the answer the repo’s call graph held all along.

Roam ships a task compiler that ends that loop. Before your prompt reaches the model, roam recognizes what kind of question it is, runs the right code-graph lookups locally (~90 ms, zero model calls), and puts the answers into the prompt: the caller list with line numbers, the git history already filtered, the source around the bug line you cited. The agent’s first words can be the answer.

For Claude Code it’s one command, zero configuration:

pip install "roam-code[mcp]"
cd your-repo && roam init
roam hooks claude --write     # compile-before + verify-after, wired into Claude Code

Then use claude exactly as you always do. Undo anytime with roam hooks claude --uninstall --write. A broken install can never block your agent — every hook is fail-open.

What that buys you, measured head-to-head on Claude (same prompts, same repo, with and without the compiler — June 2026, 41 cells):

A second run on Opus shows the same direction at smaller magnitude (−33% turns overall; the best single cell hit −88%). And the compiler knows where it doesn’t help: prompts that ask the agent to write code get no envelope at all — injection there was measured as pure overhead, so it spends your tokens only where it wins.

Headless for scripts and CI: roam compile "" --artifact auto. Prefer a dedicated product CLI? The same loop ships as compile-code — pip install git+https://github.com/Cranot/compile-code && compile claude.

The verify half of the loop — what runs after every edit

The compile half front-loads facts; the verify half reviews what the agent just changed. roam verify --auto scopes to the touched files, auto-selects the checks that make sense for what changed (Python edits unlock the Python checks, source edits unlock naming/duplicates), and runs:

• naming — against the codebase’s own per-language convention (sampled from production code only: test/vendored/generated files neither vote nor get flagged, framework lifecycle names like setUp are never touched)
• imports — the hallucination firewall: every import must resolve — to the index, the stdlib, or a declared dependency. A module path that resolves to nothing fails as a likely hallucination; near-miss names get fuzzy did-you-mean candidates
• error handling / syntax / complexity / cycles / duplicates — scoped structural review with honest disclosure when any sub-check could not run
• secrets — a leak gate over every touched file: credential shapes (cloud keys, tokens, PEM blocks) fail the check, and an optional repo-local .roam-leak-patterns.py catalogue catches the strings your project must never publish
• patterns (advisory, --deep) — the algorithm/idiom catalog scoped to the diff: N+1 query shapes, loop-invariant calls, string-concat loops, each with the better approach and a fix sketch

The fix loop. Wired via roam hooks claude --write, findings come back to the agent as an actionable list — fix or suppress, then re-verify — and the loop re-runs automatically until quiet (bounded rounds). Findings the agent disagrees with go to .roam-suppressions.yml, keyed by symbol so a suppression survives refactors that shift line numbers; the file is append-only (a suppression is never silently dropped). Everything is fail-open and quiet-on-pass: the loop surfaces only real findings, and a broken install can never block a turn.

Scoping and debt control — the flags that make verify usable on a codebase with history:

roam verify --auto                      # changed files, auto-selected checks
roam verify --diff-only                 # only lines you changed vs HEAD
roam verify --changed-lines cli.py:40-90   # exact ranges (agent harnesses)
roam verify --baseline-write            # snapshot current findings as accepted debt
roam verify --new-only                  # then: only NEW findings fail
roam verify --report --severity fail    # whole-repo ranked punch-list (non-gating)
roam verify --off / --on               # pause / resume the loop repo-wide

The commands that run beside it in the same post-edit stance:

Measured, not asserted. The detector quality is pinned by three eval suites in CI: a planted-issues recall corpus (every category must catch its canonical positives), a clean-corpus false-positive lock (dogfooded on this repo: the naming rule alone dropped ~2000 FPs when test files stopped voting), and an adversarial suppression fuzz suite (suppressions survive refactors, never lose entries).

---

What’s New

v13.6 (2026-06-11) — the verify loop grows teeth + compiler injection economics. A default secrets-leak gate and scoped algorithm sweep run after every edit; suppressions are symbol-keyed so they survive refactors; and the compiler now skips generation-shaped prompts (measured overhead) while ranking retrieval by graph importance. Full notes below · CHANGELOG.md.

Full release notes in CHANGELOG.md.

Best for

• Agent-assisted coding — structured answers that cut tokens 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 agents with conflict-aware planning
• Security analysis — vulnerability reachability, auth gaps, CVE path tracing, taint analysis
• Algorithm optimization — detect O(n²) loops, N+1 queries, and 32 other anti-patterns with suggested fixes

When NOT to use Roam

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

What’s measured vs advisory

Roam’s surfaces differ in how rigorously they’ve been validated — know which is which before you gate on them:

• Repair-intent retrieval (roam retrieve --repair-intent ) — the one surface with a preregistered, held-out, stranger-repo result. Give it the diff of a fix you just made and it reranks toward the other files that need the same repair, rather than the files that merely look similar. Measured on 576 real multi-site fixes from 12 third-party repos (rich, aiohttp, httpx, fastapi, click, flask, jinja, werkzeug, pydantic, pytest, attrs, urllib3), frozen before scoring and shipped in-repo:

  vs plain lexical search	delta	95% CI (bootstrap, n=2000)
  nDCG@10	+0.064 (0.605 vs 0.541)	[+0.032, +0.097]
  P@3	+0.041	[+0.024, +0.058]
  MRR	+0.059	[+0.026, +0.092]
  recall@10	+0.034	[−0.002, +0.070] — not significant

  That clears the preregistered bar (nDCG@10 ≥ +0.05 with a CI excluding zero) and it survived an adversarial falsifier. Read it for what it is: a real but modest improvement over lexical search on this task — not a step change. The one striking result underneath: our graph-sibling candidate pool on its own scores 0.258, far worse than lexical’s 0.541. It only beats lexical once repair-intent reranking is applied. The reranking is not polish on a good pool — it is the reason the pool is usable at all.

  Scope honestly: it needs a real patch as input, and it finds repair siblings. It is not a general-purpose search improvement, and recall is not measurably better. This is the only roam surface we would put in front of your codebase without hedging.

• Reachability triage (roam vuln-reach, roam sbom) — the most conservatively designed surface: reachability is derived only from import evidence (import sites and import edges, with file:line), never from symbol-name coincidence, so a CVE with no import evidence reports as unknown rather than reachable. Strong precision by construction; real-CVE recall on unfamiliar repos is still being measured — use it as a high-precision triage signal, and treat “unknown” as unverified rather than safe.

• Taint packs (roam taint) — validated on synthetic fixtures; real-code recall on arbitrary repositories is low/unmeasured. Treat findings as leads to investigate, not a completeness guarantee; the --ci gate is opt-in.

• Idiom & long-tail detectors (roam auth-gaps, roam missing-index, roam over-fetch, roam n1, framework idioms) — advisory. Blind precision on unfamiliar repos is not yet measured for all of them, and framework idiom detectors that measured low on stranger repos are opt-in (not on the default surface). Review each finding; don’t gate CI on these alone.

Core commands

Lead with the 5 verbs. The 5 core commands cover ~80% of agent workflows: understand, context, retrieve, preflight, critique. The remaining ~274 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 279 commands (272 canonical + 7 aliases) organised into 7 categories (aliases for muscle memory: math → algo, churn → weather, digest / snapshot / trend → trends, onboard → understand, refs → uses), but you don’t need to know that to start.

The full surface spans 7 categories — Getting Started, Daily Workflow, Codebase Health, Architecture, Exploration, Reports & CI, and Refactoring. Run roam --help for the 5-verb core, roam --help-all for every command name, and roam surface --json for the machine-readable inventory. Every command accepts roam --json for structured output and roam --sarif for CI integration (SARIF 2.1.0, honoured by 36 commands).

A few representative commands beyond the core five:

• Health & architecture: roam health (0-100 score), roam weather (churn × complexity hotspots), roam smells (24 deterministic detectors), roam algo (34-task anti-pattern catalog), roam clusters / roam layers / roam cycles.
• Change safety: roam impact (blast radius), roam diff (uncommitted-change blast radius), roam pr-risk (0-100 PR risk), roam diagnose (root-cause ranking).
• Backend quality: roam n1 (N+1 queries), roam auth-gaps, roam missing-index, roam over-fetch, roam taint (graph-reach taint, 10 rule packs).
• Index-aware search: roam search , roam grep (grep + reachability + PageRank), roam uses (graph-precise references, no string-literal false positives).
• Multi-agent: roam orchestrate --agents 3 (conflict-aware partitioning), roam fleet plan, roam lease (parallel-agent coordination).

Walkthrough

Integration with AI coding tools

Roam is designed to be called by coding agents. Instead of repeatedly grepping and reading files, the agent runs one roam command and gets a verdict-first envelope. roam preflight (above) replaces grep+read+test-impact+complexity+fitness in one ~3KB call; roam health rolls the whole codebase into one score:

$ roam health
VERDICT: Fair codebase (75/100) — 47 critical, 9 warnings, focus: god_components

Health Score: 75/100  |  Tangle: 0.0% (7/33395 symbols in cycles)
Propagation Cost: 0.1%  |  Algebraic Connectivity: 0.0074

Health: 67 issues — 47 CRITICAL, 9 WARNING, 19 INFO
  Breakdown: cycles [1 CRITICAL, 1 WARNING], god [31 CRITICAL, 8 WARNING, 11 INFO], bottlenecks [15 CRITICAL]

Top CRITICAL issues (run `roam --detail health` for the full breakdown):
  cycle (5 symbols): _COMMANDS, complete, _reconstruct_command
  god component: path (prop, degree=2408)

The verdict line works alone — an agent that reads nothing else still knows where to look. Pipe --json for the structured envelope your agent consumes.

Fastest setup (Claude Code): wire the compile/verify loop in one command — no config files, no MCP setup, no rules to write:

roam hooks claude --write           # compile-before + verify-after hooks; --uninstall to undo

For other agents (or alongside the hooks), point them at Roam via instructions in their config file:

roam describe --write               # auto-detects CLAUDE.md, AGENTS.md, .cursor/rules, etc.
roam describe --agent-prompt        # compact ~500-token prompt — copy-paste into an existing config
roam minimap --update               # inject/refresh an annotated codebase minimap (won't touch other content)

This teaches the agent which command fits each situation: roam preflight before changes, roam context for files to read, roam diagnose for debugging.

MCP Server

Roam includes a Model Context Protocol server for direct integration with MCP-aware tools.

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

Default preset: core (17 tools: 16 core + roam_expand_toolset meta-tool).

244 MCP tools span seven selectable presets (core, review, refactor, debug, architecture, compliance, full); core stays narrow to keep the prompt tight. Most tools are read-only index queries; side-effect tools are explicitly annotated. Set ROAM_MCP_PRESET=full roam mcp for the complete toolset.

Cold-start envelope. Any wrapper that can’t complete normally — missing index, stale index, partial failure — returns one canonical structured envelope (status, error_code, summary.verdict, hint, next_command) instead of hanging or emitting empty output. Agents always get an actionable signal, never a silent failure.

MCP runtime security. Three controls run at the wrapper boundary inside the server, protecting every client even with no gateway present: egress secret-redaction, mode-gated policy_decision enforcement (opt-in shadow-mode via ROAM_MODE_DRY_RUN), and HMAC-linked decision receipts bound into the signed run ledger. Gateway integrators: see dev/MCP-SECURITY-POSTURE.md.

See Using Roam via MCP for the first-run flow and canonical agent sequence.

Core preset tools: roam_alerts, roam_ask, roam_batch_search, roam_coupling, roam_dead_code, roam_deps, roam_diagnose_issue, roam_fetch_handle, roam_file_info, roam_grep, roam_metrics, roam_prepare_change, roam_search_symbol, roam_taint, roam_understand, roam_uses.

Go deeper

Pick the path that matches your role:

• 5-min demo (CTO/CISO/dev-tools-lead): The Canonical Demo — install → health → preflight → critique → signed ChangeEvidence packet, five commands, no laptop egress.
• Developer tutorial (15 min): Getting Started — install, index, query, ship.
• Agent integration: roam mcp-setup claude-code (or cursor, continue) — then Using Roam via MCP for the cold-start envelope and canonical agent loop.
• Full surface: Command Reference — every command, flag, and JSON envelope.
• Architecture: How it fits together — graph, findings registry, run ledger, evidence compiler.

CI/CD integration

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

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

roam init auto-generates this workflow. The Action accepts commands, gate (quality-gate expression, exit 5 on failure), sarif (upload to GitHub Code Scanning), comment (sticky PR comment), cache, and changed-only (incremental mode).

SARIF output. 36 commands honour the global --sarif flag (health, complexity, dead, smells, clones, vulns, taint, secrets, n1, …). Minimal upload:

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

For GitLab / Jenkins / Azure / Bitbucket templates, severity gates, and upload guardrails, see docs/ci-integration.md.

Roam Guard for PRs

roam guard-pr is the one-call CI gate that emits an Agent Change Proof Bundle v1 + closed-enum verdict (pass / pass_with_warnings / needs_review / blocked) for the current PR. Every fact carries evidence — what changed, which checks were required, which ran, why the verdict landed where it did.

# Local — show the markdown verdict for your current branch's pr-bundle.
roam guard-pr --format markdown

# CI — one line; --ci is shorthand for --strict + --init-if-missing + markdown.
roam guard-pr --ci --output guard.md

# CI — post to GitHub Check Runs (works with the default GITHUB_TOKEN).
roam guard-pr --post-check --gh-repo $REPO --gh-sha $SHA

Example reviewer markdown:

## 🛑 Roam Guard verdict: `blocked`

> **0** of **4** required checks ran. **4** missing. Risk: `low`.

### Verdict reasons
- `required_checks_not_run` (×4) — `because=config_file_changed`
  - `lint.make.lint` (detail=['.mcp.json'])
  - `test.make.test` (detail=['.mcp.json'])

### Verification checks
| Status | Command | Why |
|---|---|---|
| 🛑 missing | `lint.make.lint` | config_file_changed |
| 🛑 missing | `test.make.test` | config_file_changed |

Verdict → CI exit + GitHub conclusion map:

Output formats: text (default), markdown (PR comment / GH Check), json (the full AgentChangeProofBundle v1), sarif (GitHub Code Scanning / GitLab SAST / Defender).

Pluggable rule packs. The verification contract (what counts as a required check for a given change) lives in YAML, not code. Default pack ships with the binary; override with roam guard-pr --rules templates/examples/roam-guard-rules.default.yml:

name: my-repo
extends: default
file_patterns:
  - id: api_schema_changed
    regex: '^src/api/.*\.proto$'
    applies_to_kinds: [test, build]

JSON Schema for the v1 bundle ships at src/roam/schemas/agent_change_proof_bundle.v1.json. Validate any bundle with roam proof-bundle --validate.

See also:

• templates/examples/roam-guard-pr.github-actions.yml — drop-in GHA workflow
• templates/examples/roam-guard-pr.README.md — full adoption guide
• templates/examples/roam-guard-rules.default.yml — default rule pack

Paid layers (free CLI stays Apache 2.0)

The CLI is Apache 2.0, fully local, zero-API-key, and never expires. Three optional paid layers build on the same engine:

• Roam Review — hosted PR bot for AI-generated changes, built on roam pr-analyze. CodeRabbit/Greptile review PR semantics; Roam Review reads the graph (who calls the changed symbol, which layer it sits in) and emits a portable ChangeEvidence packet. The CLI engine is a working CI gate today: git diff main..HEAD | roam pr-analyze --gate (exit 5 on BLOCK).
• Roam Cloud — opt-in metrics history with no source upload. roam metrics-push sends a summary-only payload (numerical metrics, paths or SHA-256 hashes, identifier names) — never source-code bodies. Inspect the exact payload with --dry-run.
• PR Replay — one-shot paid audit of your last 30/90 merged PRs: a written structural-review report plus a founder walk-through. Free DIY sample via roam pr-replay --tier sample.

Early access — email [email protected]. Full pricing at .

Language Support

Tier 1 — Full extraction (dedicated parsers)

Tier 2 languages (and .jsonc / .mdx) get basic symbol extraction via a generic tree-sitter walker.

Performance

After the first full index, roam index only re-processes changed files (mtime + SHA-256 hash). Detailed indexing benchmarks across Express / Axios / Vue / Laravel / Svelte live in benchmarks/.

Compiler A/B results, the per-task gallery, routing stats, and the version-keyed eval history live in The Compiler section — one home, no duplicate numbers.

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 ── 34-task anti-pattern catalog (O(n^2) loops, N+1, recursion, async)
[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)

Exclude paths with a .roamignore file (full gitignore syntax) or roam config --exclude "*.proto". For the graph algorithms (Personalized PageRank for blast radius, Tarjan SCC, Louvain, Fiedler bisection, Mann-Kendall trend detection, …) and the weighted-geometric-mean health score, see the Architecture guide.

How Roam Compares

roam-code 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.

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 by default — zero telemetry, zero analytics, zero update checks. The single outbound surface is roam metrics-push: opt-in, summary metrics only, prints its exact payload locally under --dry-run. Source-code bodies never leave the machine.

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. roam mutate (move/rename/extract) defaults to --dry-run; pass --apply explicitly to write changes.

How does Roam handle monorepos and multi-repo projects? Monorepos: indexes from the root; batched SQL handles 100k+ symbols. Multi-repo: roam ws init builds a workspace overlay DB for cross-repo API edges, then roam ws resolve / ws context / ws trace work across repos.

Is Roam compatible with SonarQube / CodeScene? Yes — they coexist in the same CI pipeline. SARIF output uploads to GitHub Code Scanning.

Does Roam satisfy SOC 2 / ISO 42001 / EU AI Act on its own? No. Roam maps to controls and produces supporting evidence — the signed ChangeEvidence packet, HMAC-chained run ledger, and audit-trail records answer the eight evidence questions a reviewer asks after an AI-assisted change. Roam does not certify; your auditor still owns that step.

What’s the difference between the free CLI and Roam Review / Cloud / PR Replay? The CLI is Apache 2.0, fully local, and never expires. Roam Review is a hosted PR bot, Roam Cloud is opt-in metrics history with no source upload, PR Replay is a one-shot paid audit. All three are layers on top of the same engine.

Limitations

• 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 the generic tree-sitter walker.
• Large monorepos (100k+ files) may have slow initial indexing.

Troubleshooting

Update / Uninstall

# Update
pipx upgrade roam-code        # or: uv tool upgrade roam-code / pip install --upgrade roam-code

# Uninstall
pipx uninstall roam-code      # or: uv tool uninstall roam-code / pip uninstall roam-code

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

Contributing

git clone https://github.com/Cranot/roam-code.git
cd roam-code
pip install -e ".[dev]"   # includes pytest, ruff
pytest tests/              # all test cases 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