Setup
Connect Roam to your coding agent.
Give your agent code connections and free static checks it can use to explore a project, evaluate an approach, or check a change. Install the tools, index your project, then follow your agent’s connection guide. Full reference docs live at roam-code.com/docs.
1. Install the tools and index your project
Python 3.10+ and a Git repository. Works on Linux, macOS, and Windows. Free and open source under Apache 2.0.
pip install "roam-code[mcp]"
roam init
Run these commands inside your project. roam init builds the local
index in .roam/ and creates project configuration. First-run
time depends on the repository, its history, and your machine. After
changes, refresh with roam index; later runs reuse the index
and process changed files. If your agent only uses shell commands,
pip install roam-code is enough for the CLI.
Discover everything: roam --help-all (287 commands
grouped by what an agent asks) or roam tour (a suggested
reading order for your project, with top symbols and entry points). Full reference at
/docs/command-reference.
2. Connect your agent and add the workflow
MCP (Model Context Protocol) lets coding agents use Roam as a tool. Pick your agent’s guide below, connect the server, and include Roam checks in its project instructions. A connection makes tools available; it does not guarantee the agent uses them.
Claude Code
Connect the tools and add Roam to your agent's routine.
Cursor
Connect the tools and add project rules for using them.
Codex CLI
MCP setup for OpenAI Codex CLI.
Gemini CLI
MCP setup for Google Gemini CLI.
Amp
MCP setup for Sourcegraph Amp.
All platforms
Compare setup steps and check your connection.
Ask your agent to use Roam to find relevant code, check likely impact
before editing, and review the patch afterward. It should still run
tests and report missing or incomplete checks, not just successful ones.
Or run roam skill-generate --target claude to emit a SKILL.md
directly from the live capability registry.
3. Check a result against code you know
Pick a function in your project and give your agent a small first task:
Use Roam to find this function's definition and references. Show me the source locations and name any incomplete results.
Use the actual function name. Check that the result points into the intended project and inspect a returned reference in the source. An empty or incomplete result is something to investigate, not proof that the function has no callers.
Follow the first-result checklist
for connection checks and recovery steps. Then use Roam on your next code
question; refresh the index with roam index after changes.
src/roam/commands/, registered in cli.py. Apache 2.0.