[opensourcedex]

roam-code is a free, open source version control & collaboration project written in Python and released under Apache-2.0. It has 516 GitHub stars, 50 forks and 12 open issues, and was last pushed 3 days ago. On this registry it ranks #46 of 50 tracked projects in Version Control & Collaboration, with 5 head-to-head comparisons available.

What is roam-code?

roam-code is a local-first codebase intelligence CLI and MCP server that gives AI coding agents a reusable SQLite code graph, static pattern findings, and change-safety checks across 28 languages — built for developers and teams who run coding agents against their own repositories and want no API key, no account, and no automatic source-code upload.

What it is

Roam lives in the Python ecosystem and ships from PyPI as the roam-code package under the Apache-2.0 licence. It exposes 287 commands on the command line and 246 MCP tools, of which 17 sit in the default core preset. An MCP server is a standard way for agents to call tools, and Roam also allows an agent to call the CLI directly. The project runs entirely on the developer's machine, states plainly that local analysis needs no account or API key, and performs no automatic source-code or telemetry upload.

The concrete problem it solves is repeated analysis work. An agent can already read code, reason about it, and run tools, but each investigation otherwise starts from nothing: locating a dependency, judging whether a detected pattern has a better alternative, or deciding which checks a change will require. Roam replaces that from-scratch analysis with a maintained index and a set of ready checks the agent queries as it works. Static checks consume local compute rather than model calls or a paid Roam API. The index is refreshed with roam index as the code changes. The README positions the tool as useful before a defect or a patch exists — tracing a dependency, comparing an approach, or establishing which checks a change will need — and states that agents use the tools while people set direction and decide what ships.

Key capabilities

  • Builds and queries a local SQLite code graph over a repository, exposing indexed connections between files and functions.
  • Covers 28 languages and requires Python 3.10 or newer.
  • Provides 287 CLI commands and 246 MCP tools, with 17 in the default core preset.
  • Reports pattern findings together with candidate alternatives drawn from an algorithm catalog.
  • Runs static checks on local compute, without model calls or a paid Roam API.
  • Offers named entry points for inspection and triage, including roam health, roam preflight, and roam search for locating a function or class.
  • Applies change-safety gates and produces audit evidence.

Who uses it and how

  • Developers running coding agents inside an existing Git repository, who connect Roam over MCP or let the agent call the CLI.
  • Teams that want codebase analysis to stay on their own machines, with no source-code or telemetry upload.
  • Agents asked to find a function's definition and references, returning locations a person then inspects.
  • Reviewers assessing a change who need to know which checks it will require before a patch exists.
  • Shell-only agent setups, where pip install roam-code without the MCP extra is enough.

Getting started

Install with pip install "roam-code[mcp]", change into the repository, and run roam init, which builds the local index and creates project configuration; roam index builds only the index. Isolated installations are available through pipx install "roam-code[mcp]" or uv tool install "roam-code[mcp]", and the first run may download a parser and take longer than a later refresh.

How it compares

No comparable paid products are named in the supplied facts, and no analogous tools are listed either. Within this registry, roam-code stands alone in its category.

When to use it — and when not to

A self-hoster runs no separate database or mail server, since the graph is SQLite and analysis is local; the ongoing obligation is refreshing the index with roam index as the code changes. Connecting the tools over MCP does not by itself make an agent use them, because the usage instructions must also be added to the agent's project configuration, and the agent's model usage, including reading Roam's results, is billed separately. It is a poor fit for anyone expecting it to replace tests, security tooling, editor search, or code review, since the README describes it as complementary to all of those, and the recorded fresh-install transcript is explicitly historical rather than a measurement of a current checkout.

project readme (upstream, from github) — read inline

roam-code

Local code analysis and ready-to-run checks for coding agents.

Roam gives your agent a reusable codebase index, pattern findings, candidate algorithmic alternatives, and checks it can call as it works. It can investigate code and evaluate changes without building each analysis from scratch.

PyPI version GitHub stars CI Python 3.10+ License: Apache 2.0

Runs on your machine · free and open source · no account or API key for local analysis · no automatic source-code or telemetry upload

287 commands · 246 MCP tools (17 in the default core preset) · 28 languages

Connect your agent · Try a task · Documentation · Explore the code map

Why Roam is different

Your agent can read code, reason about it, and run tools already. Roam adds reusable local analyses: query indexed connections between files and functions, inspect a detected pattern with a proposed alternative, or run a scoped check. The results give your agent something concrete to inspect, test, and build on.

Static checks use local compute, not model calls or a paid Roam API. Your agent's model usage, including reading those results, is separate. Refresh the index with roam index as the code changes.

Roam is useful before there is a defect or a patch: trace a dependency, compare an approach, or establish which checks a change will need. Agents use the tools; people set direction and decide what ships. It complements your editor, search, tests, security tools, and code review.

Connect your agent

You need Python 3.10+ and a Git repository. On Linux, macOS, or Windows:

pip install "roam-code[mcp]"
cd path/to/your/repo
roam init

Replace the path with your project. init builds the local index and creates project configuration; use roam index if you want only the index. The first run can download a parser and takes longer than a refresh.

Then choose your agent's setup guide. Connect through MCP (a standard way for agents to use tools), or let your agent call the CLI. Add the usage instructions to its project configuration; connecting tools alone does not make the agent use them.

Prefer an isolated installation? Use pipx install "roam-code[mcp]" or uv tool install "roam-code[mcp]". If your agent only needs shell commands, pip install roam-code is enough. Container setup and limits.

Inspect a first result yourself
roam health
roam preflight <symbol>

Replace `` with a function or class in your project; find it with roam search . Read the returned locations, findings and missing checks, not just the score. The historical fresh-install transcript shows a recorded example, not current measurements of your checkout.

Try a task

Start with code you know. Ask your agent to use Roam to find a function's definition and references, then inspect the returned locations together. Follow the first-result checklist to confirm the intended repository, connected tools, and any incomplete results.

What you want to do What Roam supplies What the agent still does
Find where to start An overview, definitions and indexed connections Read the relevant source and check the connections
Evaluate an approach Pattern findings with alternatives from the algorithm catalog Check semantics, try a change, test and measure it
Check a change Impact analysis, related-test guidance and configured check results Run the required tests and report missing evidence

For example, roam algo can pair repeated list searches with a set or lookup-table alternative. That is a candidate, not a proven improvement: value types, updates, ordering, duplicates and returned positions can change the answer. Check behavior and measure performance before adopting it. For its MCP tool, choose the review preset and restart the server; it is not in default core.

Findings are leads. Static connections can be incomplete; a suggested test list is not test coverage, and a good health score is not permission to merge. Read the evidence limits.

Core commands

Start with these five commands. Use understand, context, retrieve, preflight, and critique for everyday exploration and change review. You can discover the rest as you need them: 287 commands (280 canonical + 7 aliases) organised into 7 categories. An alias is another name for the same command; you do not need to memorize them. Explore the remaining 282 commands when you need more detail.

Verb What it does
roam understand Get an overview of the project and where to start reading
roam context Read a definition alongside the code that calls it and the code it calls
roam retrieve "" Find useful code for a question such as “trace the login flow”
roam preflight See what a change could affect, including connected code and tests
roam critique Review a patch for related code you may have missed; pipe in git diff. High-severity findings exit 5
Discover the wider command surface

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 39 commands).

Full command reference — canonical command list (all 280)

Use the complete command index or the command reference with examples.

MCP Server

MCP lets an agent call Roam tools directly. Install with the [mcp] extra above and follow the client-specific setup. The server command is roam mcp; the client starts it for the intended project.

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

Select a wider preset for a named task by setting ROAM_MCP_PRESET in the server's environment and restarting it. roam_expand_toolset reports what is available; it does not switch the running server. See presets and tool schemas.

When consuming results, check errors, partial_success, scan scope, freshness, and any response handle before calling a check complete. Preserve useful partial findings, but do not treat missing evidence as a clean result. CLI evidence handling · MCP usage.

Default tools and package configuration

There are 8 selectable presets (core, review, refactor, debug, architecture, compliance, compile-curated, full). Choose by the task; the preset guide explains their contents.

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.

roam_ask (CLI: roam ask) routes a supported question to a recipe from the 31-recipe registry. It is a deterministic dispatcher, not a model conversation.

The full 246-tool table with descriptions lives in docs/mcp-tools.md.

Which preset ships where. The Claude Code plugin selects core for a smaller tool list. This repository's own .mcp.json selects full so agents working on Roam can test the wider surface. The difference is intentional.

Integration with AI coding tools

Use the integration guides for supported clients and project instructions. Review generated instructions before adding them to an existing agent configuration.

roam describe --agent-prompt

This prints guidance to inspect and incorporate; it does not establish that your agent has followed the workflow. The agent CLI guide covers bounded calls and incomplete output.

Context for your agent

Roam's task compiler can attach locally prepared context to a prompt: callers, recent changes, or source around a reported bug. It makes no model calls. Optional Claude Code hooks combine that preparation with post-edit checks:

roam hooks claude --write

Run from the initialized project. Undo with roam hooks claude --uninstall --write. Compile-time context injection is fail-open; the edited-turn Stop gate blocks failing, unavailable, malformed or incomplete verification. Read the hook compatibility and check workflow before enabling it. Installation does not prove the hooks executed.

compile-code provides a dedicated driver for the same preparation-and-verification loop. Historical comparisons and losses are dated experiments, not a promise for your model or repository.

Check the work after an edit

roam verify --auto chooses checks for changed files. The verification workflow explains what can run, how missing evidence is handled, and how reviewed exceptions work. It does not replace your project's required test suite.

CI/CD integration

Use the CI integration guide for GitHub, GitLab, Jenkins, Azure or Bitbucket. Generate configuration explicitly with roam ci-setup --platform github --write or roam init --with-ci=github; plain roam init does not change CI configuration.

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

jobs:
  roam:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 0
          persist-credentials: false
      # For production, replace the tag with the reviewed 40-character SHA it
      # points at — a release tag is readable but remains movable.
      - uses: Cranot/roam-code@v14.1.0
        with:
          version: '14.1.0'
          commands: health
          gate: "score>=70"
          sarif: 'true'
          comment: 'true'

Review permissions and pin actions to reviewed commit SHAs before adoption. A quality-score gate is one configured check, not permission to merge.

SARIF output. 39 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@03e4368ac7daa2bd82b3e85262f3bf87ee112f57 # v3.36.0
  with:
    sarif_file: roam-health.sarif

Roam Guard for PRs

roam guard-pr gathers a change's review record: what changed, which checks were required, what ran, and what remains missing. Use --ci or --strict when it must gate CI; reporting-only mode can exit 0 with a blocking verdict.

roam guard-pr --ci --output guard.md

The adoption guide covers verdicts, exit codes, rules, and CI setup. Verification evidence explains what a saved record establishes. Signed records can reveal later changes to evidence; they do not authenticate every supplied claim or establish that all relevant checks ran.

Best for

Repeated repository investigations, implementation choices, refactor planning, and change checks in an agent's workflow. Try a real task on your own code and inspect the evidence, false positives and time involved before adding a gate.

When NOT to use Roam

Use an LSP for compiler-backed type resolution, ripgrep for raw text search, and your test runner for runtime behavior. A small script may be quicker to read directly. Roam complements these tools; it does not replace them.

What's measured vs advisory

The measurement record separates historical agent comparisons, held-out repair-sibling retrieval results, and unmeasured detector accuracy. It preserves losses and limitations alongside wins. No general accuracy or savings claim follows from a passing regression suite.

Language Support

Python, JavaScript, TypeScript, Go, Rust, Java, C#, PHP, Ruby, Salesforce and more. The language support table lists extractors and supported constructs. Extraction depth varies by language and framework; a recognized file extension is not complete semantic or runtime coverage.

Performance

Indexing cost depends on your source, Git history, machine and parser cache. Refresh with roam index after changes; unchanged source can be reused. Historical timings and benchmark results are context, not a latency promise. Measure the commands your workflow uses.

How It Works

Roam discovers files, parses source, extracts symbols, resolves references, and stores the local model in SQLite. Graph analysis, Git history, detector rules and supported experiments supply different kinds of observations.

See the architecture and explore the illustrative code atlas. Exclude paths with .roamignore or roam config --exclude "*.proto".

How Roam Compares

Choose Roam for callable local code analysis and checks alongside your agent, not as another coding agent or a replacement for specialist review. Its MCP inventory is 246 (17 in default core preset); select tools for the task. Compare the roles, then evaluate the outputs on your own repository: resolution, false positives, latency, and usefulness.

Paid layers (free CLI stays Apache 2.0)

The CLI and MCP server are free under Apache 2.0 for individuals and teams. Static checks use local compute, not model calls; your agent's model charges are separate. You do not need a paid service to use Roam with your agents.

  • PR Replay — paid report by request. A written assessment of an agreed change history, reviewed findings, and a founder walk-through. The existing Team and Deep scopes define the PR window; agree how commits map to those PRs before kickoff. Try the free local sample with roam pr-replay --tier sample. Its default range is HEAD~5..HEAD, not necessarily five PRs; your checkout needs that history. A replay does not prove that an incident would have been prevented.
  • Roam Review — planned, not available to subscribe to. A proposed hosted pull-request check using Roam's local analysis. The hosted app, installation flow, and billing are not built yet.
  • Roam Cloud — planned, not available to subscribe to. A proposed shared history of codebase measurements. The local roam metrics-push command exists; that does not establish a hosted dashboard. Inspect its payload with --dry-run.

See pricing and paid help and the PR Replay sample and scope. Questions go to hello@roam-code.com; describe the task first, without source code, credentials, or private reports. Availability and written terms are agreed before work starts.

FAQ

Does Roam send any data externally? Not during ordinary local analysis. Roam does not automatically upload source code, indexes, findings, telemetry, or analytics, and it performs no automatic update check. On first use, tree-sitter-language-pack downloads a checksum-verified parser bundle and keeps it in a local cache. Explicit features can contact PyPI, GitHub, user-selected URLs, Roam Cloud, or Sigstore services; docs/network-boundary.md lists every built-in trigger, destination, and payload class. Inspect roam metrics-push with --dry-run before sending its allow-listed payload.

Can Roam run in air-gapped environments? Yes, after installation and parser prewarming. Run roam index --force once while connected on each target platform; the retained bundle lets later grammar loads complete without network access. Avoid the explicit network triggers in the network-boundary inventory, use fixture/file inputs and offline-key signing, and enforce egress policy around project commands launched by roam verify or hooks.

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.

Can I control where and when the index is built? Set ROAM_DB_DIR to redirect the SQLite database and its index.lock / index.state sidecars together, or save a per-project location with roam config --set-db-dir. Set ROAM_NO_AUTO_INDEX=1 to refuse implicit builds: an analysis command needing a missing or incomplete index exits 3 and emits a structured refusal in JSON mode. roam index and roam init still build when explicitly invoked. Use roam index if you only want to build the index; init intentionally also creates project configuration. The storage override does not redirect agent ledgers, response evidence, or other requested artifacts. Stop older indexers before upgrading or changing store locations; do not run mixed-version writers against one store.

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. Configured Roam workflows can produce supporting records: ChangeEvidence packets, a run ledger, and audit-trail records. Read which checks and supplied decisions were captured, and which evidence is missing. These records do not authenticate who acted or prove complete coverage. Roam does not certify; framework applicability and assessment need appropriate specialist review.

What's the difference between the free CLI and Roam Review / Cloud / PR Replay? The CLI and MCP tools are free under Apache 2.0; their static checks run locally without model calls. Your agent's model usage is separate. PR Replay offers a free local sample and paid reports with founder review, by agreed scope. Roam Review and Roam Cloud are planned hosted products, not available to subscribe to. See pricing and availability.

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

Problem Solution
roam: command not found Ensure install location is on PATH. For uv: uv tool update-shell
Another indexing process owns the workspace Wait for the active writer and run roam doctor. A live or unprovable owner requires investigation; preserve .roam/index.lock and the lifecycle marker. Proven abandoned generations are recovered by the indexer.
database is locked Finish the active indexer or watcher, close other database writers, and check for cloud-sync interference. Then retry roam index; rebuilding does not bypass a live SQLite lock.
ROAM_NO_AUTO_INDEX refusal (exit 3) Run roam index explicitly after selecting the intended project and store, or unset the opt-out to restore automatic cold-start builds. JSON refusals distinguish missing and incomplete indexes without opening the database.
Unicode errors on Windows chcp 65001 for UTF-8
Symbol resolves to wrong file Use file:symbol syntax: roam symbol myfile:MyFunction
Health score seems wrong roam health --explain for score contributions; use roam --json health for structured findings. The architectural score is separate from test and environment health.
Index stale after git pull or a commit roam index refreshes source and Git metadata, including commits with unchanged file contents. Use roam index --force to rebuild derived index data.

See the troubleshooting guide and repository maintenance guide for environment repair, index recovery, and the meaning of doctor advisories.

Go deeper

Walkthrough

Follow the worked example from a first scan to a configured review record, or browse illustrative changes.

Watch a recorded terminal demo

roam terminal demo

This is a historical CLI recording, not a live run or a current-output contract. Use the linked guides above for the maintained workflow.

What's New

Read the changelog for released changes and the Unreleased section for work awaiting a release. A source checkout may be ahead of the package installed from PyPI.

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

Before removing .roam/, back up any rules, annotations, memory, signed run ledgers, keys, or proof bundles you need to retain. That directory contains project state as well as the rebuildable index; uninstalling the package does not require deleting it.

Contributing

git clone https://github.com/Cranot/roam-code.git
cd roam-code
uv sync --locked --no-default-groups --extra dev --group ci --python 3.12
uv run --no-sync pytest tests/test_basic.py -n 0

Follow CONTRIBUTING.md for the full test/release gates and the documentation map for maintained guides and references.

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

Frequently asked questions

Is roam-code free to use?

roam-code is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does roam-code do?

Local codebase intelligence CLI + MCP server for AI coding agents: SQLite code graph, 28 languages, 287 commands, 246 MCP tools, change-safety gates, audit evid

What is roam-code written in?

roam-code is primarily written in Python. Its source is publicly available at https://github.com/Cranot/roam-code, and it has 516 GitHub stars.