roam-code

Roam-code is the architectural intelligence layer for AI coding agents. It indexes a codebase into a semantic graph, capturing symbols, dependencies, call graphs, architecture layers, git history, and runtime traces. The Roam CLI exposes a broad set of MCP tools (over 100) that let agents query, analyze, and reason about code structure locally, without external APIs. Typical workflows involve querying the graph to understand relationships, running health checks, performing preflight analysis before changes, and orchestrating multi-step refactor or governance tasks. The core commands include roam understand to generate a comprehensive briefing about the repository, roam context <name> to extract the most relevant files and line ranges, roam preflight <name> to assess blast radius, tests, complexity and governance rules, roam health to obtain a composite quality score, and roam diff to see the blast radius of uncommitted changes. These tools enable agent-driven code understanding, safe refactoring, and architecture governance all within a single local CLI.

Prerequisites:

• Python 3.9+ installed on your system
• Internet access to fetch the package from PyPI (optional if you already have the wheel)

Installation steps:

1. Create and activate a Python virtual environment (recommended):
   • On macOS/Linux: python3 -m venv roam-env && source roam-env/bin/activate
   • On Windows: python -m venv roam-env && roam-env\Scripts\activate
2. Install the Roam-Code package from PyPI:
   • pip install roam-code
3. Verify installation by running a help/version command (example may vary by CLI):
   • roam --version
4. Run the MCP server entry if applicable (example using module invocation):
   • python -m roam_code

Optional:

• If you prefer a local, isolated setup, keep ROAM_CODE_HOME (data directory) inside your project or user directory and point Roam-Code to it via environment variables.

Notes and tips:

• Roam-Code runs locally and supports offline operation with a local SQLite graph DB.
• The MCP tools are exposed via a single CLI; you can script agent workflows by chaining commands like roam understand, roam context, roam preflight, roam health, and roam diff.
• Environment variables can be used to customize logging and data paths. For example, ROAM_DEBUG=1 enables verbose logging to help diagnose issues.
• If you encounter missing language extractors or tool capabilities, ensure your Roam-Code installation is up to date with the latest MCP toolset; some commands may require optional components or data models to be downloaded on first run.
• Since this is a local, offline-friendly MCP server, there is no need for API keys or external services to operate standard analysis and governance tasks.