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 ──> 136 Commands ──> AI Agent
              │              │                  │
           tree-sitter    symbols            comprehend
           26 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

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.

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

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

Claude Code • Cursor • Windsurf • GitHub Copilot • Aider • Cline • Gemini CLI • OpenAI Codex CLI • MCP • GitHub Actions • GitLab CI • Azure DevOps

Commands

The 5 core commands shown above cover ~80% of agent workflows. 136 canonical commands (+1 legacy alias = 137 invokable names) are organized into 7 categories.

$ 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

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

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

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

Walkthrough: Investigating a Codebase

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

$ 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

$ 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

$ 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

$ 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

$ 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

$ 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

$ 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

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

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

$ roam health --gate score>=70
Health: 78/100 — PASS

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

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

claude mcp add roam-code -- roam mcp

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

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

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

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

CI/CD Integration

All you need is Python 3.9+ 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:
          command: health --gate score>=70
          comment: true
          fail-on-violation: 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 score>=70
    - roam --json pr-risk origin/main..HEAD > roam-report.json
  artifacts:
    paths:
      - roam-report.json
  rules:
    - if: $CI_MERGE_REQUEST_IID

pip install roam-code
roam index
roam health --gate score>=70    # exit 1 on failure
roam --json health > report.json

SARIF Output

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

from roam.output.sarif import health_to_sarif, write_sarif

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

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

For Teams

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

Language Support

Tier 1 -- Full extraction (dedicated parsers)

| Ruby | .rb | classes, modules, methods, singleton methods, constants | require, require_relative, include/extend, calls, ClassName.new | class inheritance | | JSONC | .jsonc | via JSON grammar | -- | -- | | MDX | .mdx | via Markdown grammar | -- | -- |

Tier 2 -- Generic extraction

Kotlin (.kt .kts), Swift (.swift), Scala (.scala .sc)

Tier 2 languages get symbol extraction and basic inheritance via a generic tree-sitter walker.

Performance

Agent-efficiency benchmark write-up: reports/09_agent_efficiency_benchmarks.md.

How It Works

Codebase
    |
[1] Discovery ──── git ls-files (respects .gitignore + .roamignore)
    |
[2] Parse ──────── tree-sitter AST per file (26 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.

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.

Interactive docs site (GitHub Pages artifact, published by .github/workflows/pages.yml):

• docs/site/index.html (landing)
• docs/site/getting-started.html (tutorial)
• docs/site/command-reference.html (examples)
• docs/site/architecture.html (diagram + internals)
• docs/site/landscape.html (competitor matrix)

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 (Kotlin, Swift, Scala) get basic symbol extraction only
• 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/              # 2656 tests, Python 3.9-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 (136 canonical commands + 1 legacy alias)
│   ├── mcp_server.py                  # MCP server (101 tools, 10 resources, 5 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 (17 Tier 1)
│   │   └── 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
│   │   ├── split.py, why.py           # Decomposition, role classification
│   │   └── 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
│   ├── 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
│   ├── 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/                             # Test suite across 70 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]"

Roadmap

Shipped

• MCP v2 agent surface: in-process execution, compound operations, presets, schemas, annotations, and compatibility profiles.
• Full command and MCP inventory parity in docs: 136 canonical CLI commands (+1 alias) and 101 MCP tools.
• CI hardening: composite action, changed-only mode, trend-aware gates, sticky PR updater, and SARIF guardrails.
• Performance foundation: FTS5/BM25 search, O(changed) incremental indexing, DB/index optimizations.
• Agent governance suite: vibe-check, ai-readiness, verify, ai-ratio, duplicates, advanced algo scoring/SARIF.
• Ownership/review intelligence: codeowners, drift, simulate-departure, suggest-reviewers, api-changes, test-gaps, semantic-diff, secrets.
• Multi-agent operations: partition, affected, syntax-check, workspace-aware context and traces.
• Budget-aware context delivery: --budget (partial rollout), PageRank-weighted truncation, conversation-aware ranking.

Next (v11 Closeout + immediate follow-up)

• Terminal demo GIF in README (#26).
• GitHub repo topics (#24).
• GitHub Discussions enabled (#29).
• MCP directory + awesome-list submissions (#31).
• Optional community launch note (#32, post-v11, non-blocking).
• Keep roadmap synchronized with shipped state (#112 recurring hygiene).

Contributing

git clone https://github.com/Cranot/roam-code.git
cd roam-code
pip install -e .
pytest tests/   # All 2656 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

MIT