roam-code: a local code graph and MCP server for coding agents

The problem roam-code addresses: agents editing code they cannot see

A coding agent asked to change a function usually has two ways to learn about the surrounding code: read files until it runs out of context, or run a text search and guess at the results. Neither tells it who calls the function, which tests touch it, or how far a change could propagate. roam-code is built for that gap. It constructs a reusable map of functions, classes, imports and their connections, and lets the agent query the map through the CLI or through MCP, the Model Context Protocol. The README frames the difference in one line: a search finds a name, roam-code helps you follow where that name is defined and used. The intended user is not the engineer typing at a terminal all day. It is the agent doing the typing, with the engineer inspecting the same results when something looks wrong.

What the index actually contains and how queries reach it

The mechanism is a local static analysis pass that produces a SQLite code graph. Parsing is done with tree-sitter, which is how the project reaches 28 languages from a single Python codebase. The graph holds symbols and the edges between them: definitions, callers, imports, and the file-level relationships that let a query answer "what else could my change affect". Two surfaces sit on top of that graph. The first is the CLI, which the README says exposes 287 commands. The second is an MCP server exposing 246 tools, of which 17 are in the default core preset. That default matters: an agent handed 246 tools will spend context deciding which to call, so the preset is the practical entry point and the rest are opt-in. Everything runs locally. The README states that local analysis needs no account or API key and that the tool does not automatically upload code, index, findings, or telemetry. Installation and the first parser download do require network access, and the project points readers at docs/network-boundary.md before use in a restricted environment.

Install and the first four commands

The README gives a four-command sequence. Install the CLI plus the optional agent-tool server with pip install "roam-code[mcp]", change into the repository, run roam init to build the local index and project configuration, then roam health for a summary of code structure and findings, and roam preflight <symbol> to check a function or class before changing it. Python 3.10 or newer is required. pipx install roam-code and uv tool install roam-code are listed as alternatives, and dropping the [mcp] extra gives a CLI-only install. If you want the index without project configuration, use roam index instead of init. To find a symbol to test preflight against, run roam search <name>. The README notes that the first index takes longer than later refreshes and that timing depends on repository size and machine. It also links docs/fresh-install-smoke.md, described as a verbatim transcript of those four commands against a clean virtual environment, which is the right thing to read before trusting the sequence on your own setup.

What preflight reports, and what the numbers mean

The README includes a recorded run of roam preflight open_db against roam-code's own codebase. It prints a verdict line, then a block with blast radius, affected tests, complexity, coupling, conventions and fitness, followed by an overall risk and the driver behind it. In that snapshot the blast radius is 17922 symbols across 1732 files, rated CRITICAL, with 681 direct and 14126 transitive tests, cyclomatic complexity 5, nesting 2, and no convention violations. The README is careful about interpretation, and this is the most useful part of the documentation: blast radius means code that could be affected through the indexed connections, not code that will break. The counts are a snapshot from that repository, not live measurements of yours. That distinction is the difference between a tool that informs a decision and one that produces alarm. Read the affected-tests figure the same way. It is a list of tests connected to the symbol through the graph, and the README says explicitly that a suggested test list is not test coverage.

Roam Guard, audit evidence, and the limits of a signed record

For teams that need a review record, the README describes a PR gate and a saved record of what changed, which checks ran, and why a gate passed or stopped. It also states the boundary of that record in the same breath: signed records can reveal later changes to the evidence, but they cannot prove that every relevant check was captured. That is an honest framing and worth taking literally. A gate proves the checks you configured ran and passed. It does not prove you configured the right checks. The README links docs/concepts/verification-evidence.md for the full account, and anyone planning to attach these records to a compliance process should read that page before designing the workflow around it. The same caution applies to the health score: the README says a good health score is not permission to merge.

Where roam-code is the wrong tool

The connections come from static analysis, so they can be incomplete. Anything resolved at runtime, through dynamic dispatch, reflection, dependency injection containers, generated code, or string-based imports, may not appear as an edge in the graph. If your codebase leans heavily on those patterns, the blast radius and affected-test figures will undercount, and undercounting is worse than no number because it looks authoritative. The 28-language claim is a ceiling across the project, not a promise about your repository: a polyglot repo with a language outside that set gets a partial graph, and the README does not describe per-language depth. Local-first also has a cost. The first index takes longer than later refreshes, the first parser download needs network access, and a large repository means a large SQLite index on disk. Restricted environments should check docs/network-boundary.md first. Finally, none of this replaces running the tests. The tool tells an agent where to look; it does not tell you the change is correct.

How it differs from language servers and from hosted code-intelligence services

The closest thing most engineers already have is a language server. A language server answers questions about the file you have open, in your editor, for one language, and it is optimized for interactive latency. roam-code answers repository-wide questions in a form an agent can consume, across 28 languages, and persists the answers in SQLite so a query does not require re-parsing. The trade-off is depth: a dedicated language server understands its language's type system far better than a tree-sitter pass can, so for a single-language Python or TypeScript repository, hover and go-to-definition in the editor will beat roam-code on precision. The other comparison is hosted code-intelligence services that index a repository server-side and bill per seat or per query. roam-code's difference is the deployment shape: the index stays on the machine, local analysis needs no API key, and the agent's own model usage is separate from the analysis. That matters if your code cannot leave the network, or if you do not want analysis cost to scale with query volume. It matters less if you want cross-repository search or a shared index across a large team, which the README does not describe.

Maintenance, upgrade cost, and the licence

The release cadence visible in the material is fast: v14.0.3 and v14.0.4 both landed on 2026-09-05, and v14.1.0 on 2026-09-09. Three releases in five days suggests active development, and it also means a pinned version is the safer default for a CI gate, since a gate whose behaviour changes under you is a gate you stop trusting. The README mentions paid layers while stating that the free CLI stays Apache-2.0, so the core analysis you are evaluating here is not going to be pulled behind a paywall, but the boundary between free and paid is defined on the project's pricing page rather than in the README. Read that page yourself before assuming a feature is in the free tier. Apache-2.0 permits commercial use and modification and includes a patent grant; it also requires that you preserve licence and notice files and state significant changes. That is a summary of the licence text, not legal advice. If you fork the project or ship it inside a product, have someone who can read the actual licence confirm what your distribution requires.

Editorial conclusion

Adopt roam-code if your workflow already hands edits to a coding agent and you want it to query a local index of definitions and callers instead of grepping file by file, and if you can accept that the graph reflects static analysis rather than runtime behaviour. Do not adopt it as a replacement for tests, coverage tooling, or human review: the README states plainly that a suggested test list is not test coverage and a good health score is not permission to merge. Before wiring it into an agent, verify three things on your own repository: that the languages you care about are among the 28 supported, that the first parser download and index build fit your network and disk constraints, and that the core preset of 17 MCP tools gives your agent the queries it actually needs rather than all 246.

Official sources

1. Cranot/roam-code on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases