Cranot/roam-code

roam-code is a local code analysis toolkit designed to give AI coding agents a reusable understanding of a codebase. It builds an index of your project's symbols, connections, and patterns, then exposes that as commands and MCP tools the agent can call while working.

What it does

• Indexes your code locally: parses source, extracts functions/classes, resolves references, and stores everything in a SQLite database.
• Provides ready-made checks (static analysis, pattern detection, impact analysis) that run on your machine without any model calls or cloud service.
• Integrates with agents via MCP (Model Context Protocol) or a CLI, so an agent can query the index, inspect code, and evaluate changes without rebuilding analysis from scratch.

Key commands (the “core five”)

• roam understand – overview of the project and where to start reading.
• roam context <symbol> – shows a definition plus the code that calls it and it calls.
• roam retrieve "<task>" – finds relevant code for a question like “trace the login flow.”
• roam preflight <symbol> – predicts what a change could affect (connected code, tests).
• roam critique – reviews a patch for related code you might have missed (pipe in git diff).

How it works

• Discovers files, parses them (using tree-sitter), extracts symbols, resolves references, and stores the model in SQLite.
• Graph analysis, Git history, and detector rules supply different kinds of observations.
• Static checks use local compute only; your agent’s model usage is separate.
• Refresh the index with roam index as code changes.

Integration

• Connect via MCP (the server command is roam mcp) or let the agent call the CLI directly.
• 258 MCP tools across 8 presets (default core has 17).
• Can generate CI configurations (GitHub, GitLab, etc.) and produce SARIF output for 39 commands.
• Optional Claude Code hooks add compile-time context and post-edit verification.

Privacy & cost

• Runs entirely on your machine; no automatic upload of source, indexes, or telemetry.
• Free and open source (Apache 2.0). No API key needed for local analysis.
• Paid layers (PR Replay, Roam Review, Roam Cloud) are either by request or still planned; the free CLI stays fully functional.

Limitations

• Static analysis can be incomplete; findings are leads, not proof.
• Not a replacement for LSP, ripgrep, or your test runner – it complements them.
• Extraction depth varies by language; a recognized file extension isn’t full semantic coverage.

Best for repeated repository investigations, implementation choices, refactor planning, and change checks in an agent’s workflow.