roam-code MCP工具

Docker (local build; CLI + MCP dependencies)

docker build -t roam-code . docker run --rm --user "$(id -u):$(id -g)" -e HOME=/tmp -v "$PWD:/workspace" roam-code index docker run --rm --user "$(id -u):$(id -g)" -e HOME=/tmp -v "$PWD:/workspace" roam-code health ```

Works on Linux, macOS, and Windows. Windows: if roam is not found after installing with uv, run uv tool update-shell and restart your terminal.

</details>

---

<a id="the-compiler--your-agents-first-token-already-knows-the-answer"></a>

Install + first four commands

Install Roam in a Git repository your agent works on. The commands below are also a quick way to inspect what the agent will get; for ongoing use, follow the agent setup guide and include checks before and after edits in its instructions.

pip install "roam-code[mcp]"          # 1. install the CLI and optional agent-tool server
cd /path/to/your/repo
roam init                            # 2. build the local index and project configuration
roam health                          # 3. see a summary of code structure and findings
roam preflight <symbol>              # 4. check a function or class before changing it

Python 3.10+. pipx install roam-code and uv tool install roam-code work too. Drop [mcp] for CLI-only. See docs/fresh-install-smoke.md for a verbatim transcript of these four commands against a clean venv.

Replace <symbol> with a function or class from your project. To find one, run roam search <name>. The first index takes longer than later refreshes; timing depends on repository size and your machine. Use roam index instead of init if you only want the index, without creating project configuration.

Here is a recorded example from Roam's own codebase. open_db is used widely, so the report calls out the size of the change before you make it. The counts below are a snapshot, not live measurements of your checkout:

$ roam preflight open_db
VERDICT: Significant risk — CRITICAL, 17922 symbols in blast radius

Pre-flight check for `open_db (src/roam/db/connection.py:1076)`:

  Blast radius:     17922 symbols in 1732 files              [CRITICAL]
  Affected tests:   681 direct, 14126 transitive             [OK]
  Complexity:       cc=5, nest=2                             [LOW]
  Coupling:         2 files often change together            [MEDIUM]
  Conventions:      no violations                            [OK]
  Fitness:          target passes; 1 rule(s) fail on sibling symbols [OK]

  Overall risk: CRITICAL
  Risk driver:  blast radius (17922 symbols in 1732 files, CRITICAL)

“Blast radius” means code that could be affected through the indexed connections; it does not mean all of those functions will break.

<details> <summary><strong>Alternate install methods + Docker</strong></summary>

```bash pipx install roam-code # isolated environment (recommended) uv tool install roam-code # uv-managed tool pip install git+https://github.com/Cranot/roam-code.git # from source

Paid layers (free CLI stays Apache 2.0)

The CLI is Apache 2.0, uses a local zero-API-key analysis engine, and never expires. Three optional paid layers build on the same engine:

• Roam Review — hosted PR bot for AI-generated changes, built on roam pr-analyze. CodeRabbit/Greptile review PR semantics; Roam Review reads the graph (who calls the changed symbol, which layer it sits in) and emits a portable ChangeEvidence packet. The CLI engine is a working CI gate today: git diff main..HEAD | roam pr-analyze --gate (exit 5 on BLOCK).
• Roam Cloud — opt-in metrics history with no source upload. roam metrics-push sends a summary-only payload (numerical metrics, paths or SHA-256 hashes, identifier names) — never source-code bodies. Inspect the exact payload with --dry-run.
• PR Replay — one-shot paid audit of your last 30/90 merged PRs: a written structural-review report plus a founder walk-through. Free DIY sample via roam pr-replay --tier sample.

Early access — email hello@roam-code.com. Full pricing at <https://roam-code.com/pricing>.

Integration with AI coding tools

Roam is designed to be called by coding agents. Instead of repeatedly grepping and reading files, the agent runs one roam command and gets a verdict-first envelope. roam preflight (above) replaces grep+read+test-impact+complexity+fitness in one ~3KB call; roam health rolls the whole codebase into one score:

$ roam health
VERDICT: Fair codebase (77/100) — 65 critical, 0 warnings, focus: god_components

Health Score: 77/100  |  Tangle: 0.0% (0/44056 symbols in cycles)
Propagation Cost: 6.0%  |  Algebraic Connectivity: 0.0146

Health: 65 issues — 65 CRITICAL, 37 INFO
  (0 actionable cycles, 37 local/test cycles ignored, 50 god components
   (19 actionable, 31 expected utilities), 15 bottlenecks (2 actionable))
  Breakdown: cycles [0 issues], god [50 CRITICAL], bottlenecks [15 CRITICAL], layers [0 issues]

Top CRITICAL issues (run `roam --detail health` for the full breakdown):
  god component: result (prop, degree=2198)
  god component: path (prop, degree=677)

The verdict line works alone — an agent that reads nothing else still knows where to look. Pipe --json for the structured envelope your agent consumes.

Fastest setup (Claude Code): wire the compile/verify loop in one command — no config files, no MCP setup, no rules to write:

roam hooks claude --write           # compile-before + verify-after hooks; --uninstall to undo

For other agents (or alongside the hooks), point them at Roam via instructions in their config file:

roam describe --write               # auto-detects CLAUDE.md, AGENTS.md, .cursor/rules, etc.
roam describe --agent-prompt        # compact ~500-token prompt — copy-paste into an existing config
roam minimap --update               # inject/refresh an annotated codebase minimap (won't touch other content)

This teaches the agent which command fits each situation: roam preflight before changes, roam context for files to read, roam diagnose for debugging.

<details> <summary><strong>Where to put agent instructions for each tool</strong></summary>

</details>

CI/CD integration

All you need is Python 3.10+ and pip install roam-code.

```yaml

.github/workflows/roam.yml

name: Roam Analysis on: [pull_request]

jobs: roam: runs-on: ubuntu-24.04 steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 with: fetch-depth: 0 persist-credentials: false # For production, replace the tag with the reviewed 40-character SHA it # points at — a release tag is readable but remains movable. - uses: Cranot/roam-code@v14.0.4 with: version: '14.0.4' commands: health gate: "score>=70" sarif: 'true' comment: 'true'

Generate this workflow explicitly with `roam init --with-ci=github` or
`roam ci-setup --platform github --write`; plain `roam init` does not modify CI configuration.
The Action accepts `commands`, `gate` (quality-gate expression, exit 5 on
failure), `sarif` (upload to GitHub Code Scanning), `comment` (sticky PR
comment), `cache`, and `changed-only` (incremental mode).


**SARIF output.** 39 commands honour the global `--sarif` flag (health, complexity, dead, smells, clones, vulns, taint, secrets, n1, …). Minimal upload:

For GitLab / Jenkins / Azure / Bitbucket templates, severity gates, and upload guardrails, see docs/ci-integration.md.

What's measured vs advisory

Roam's surfaces differ in how rigorously they've been validated — know which is which before you gate on them:

• Repair-intent retrieval (roam retrieve --repair-intent <patch>) — the one surface with a preregistered, held-out, stranger-repo result. Give it the diff of a fix you just made and it reranks toward the other files that need the same repair, rather than the files that merely look similar. Measured on 576 real multi-site fixes from 12 third-party repos (rich, aiohttp, httpx, fastapi, click, flask, jinja, werkzeug, pydantic, pytest, attrs, urllib3), frozen before scoring and shipped in-repo:

| vs plain lexical search | delta | 95% CI (bootstrap, n=2000) | |---|---|---| | nDCG@10 | +0.064 (0.605 vs 0.541) | [+0.032, +0.097] | | P@3 | +0.041 | [+0.024, +0.058] | | MRR | +0.059 | [+0.026, +0.092] | | recall@10 | +0.034 | [−0.002, +0.070] — not significant |

That clears the preregistered bar (nDCG@10 ≥ +0.05 with a CI excluding zero) and it survived an adversarial falsifier. Read it for what it is: a real but modest improvement over lexical search on this task — not a step change. The one striking result underneath: our graph-sibling candidate pool on its own scores 0.258, far worse than lexical's 0.541. It only beats lexical once repair-intent reranking is applied. The reranking is not polish on a good pool — it is the reason the pool is usable at all.

Scope honestly: it needs a real patch as input, and it finds repair siblings. It is not a general-purpose search improvement, and recall is not measurably better. This is the only roam surface we would put in front of your codebase without hedging. - Reachability triage (roam vuln-reach, roam sbom) — the most conservatively designed surface: reachability is derived only from import evidence (import sites and import edges, with file:line), never from symbol-name coincidence, so a CVE with no import evidence reports as unknown rather than reachable. Strong precision by construction; real-CVE recall on unfamiliar repos is still being measured — use it as a high-precision triage signal, and treat "unknown" as unverified rather than safe. - Taint packs (roam taint) — validated on synthetic fixtures; real-code recall on arbitrary repositories is low/unmeasured. Treat findings as leads to investigate, not a completeness guarantee; the --ci gate is opt-in. - Idiom & long-tail detectors (roam auth-gaps, roam missing-index, roam over-fetch, roam n1, framework idioms) — advisory. Blind precision on unfamiliar repos is not yet measured for all of them, and framework idiom detectors that measured low on stranger repos are opt-in (not on the default surface). Review each finding; don't gate CI on these alone.

How Roam Compares

Choose Roam when you want a reusable local map of how a project fits together. Use this checklist to see whether it helps with your own code: