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.

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

288 commands · 259 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 <symbol> with a function or class in your project; find it with roam search <name>. 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.