roam-code：AI agent がコードを直す前に code graph を見せる
AI coding agent がつまずきやすいのは、局所的なコードを書けないことより、その変更がリポジトリ全体のどこに効くかを見落とすことだ。
関数名で検索して十数ファイルが出る。agent はそのうち三、四ファイルを読んで編集を始める。テストは通るが、間接的な call path が壊れる。あるいは文字列検索だけで影響範囲を判断し、dynamic import、call graph、architecture layer、過去に一緒に変更されがちなファイルを落とす。人間の reviewer が本当に知りたいのは、「テストは緑か」だけではない。「編集前に何を読んだのか、どのリスクを認識したのか、何を検証したのか」だ。
今日メモしておきたい Cranot/roam-code は、この問題に向いたローカル codebase intelligence layer である。新しい chat UI ではなく、リポジトリをローカル SQLite に索引し、symbol、call、imports、dependency、git history、runtime traces、smells、clones、security flows、algorithmic patterns を CLI と MCP から引ける構造化事実にする。agent は編集前に roam preflight で blast radius を見て、編集後に roam verify --auto で scoped check を走らせ、その過程を evidence として残せる。
2026-07-10 時点で GitHub repository page、README、LICENSE、release page、git tags、浅い clone の commit history、GitHub HTML metadata から確認できる公開情報では、Cranot/roam-code は 495 stars、47 forks。主言語は Python、ライセンスは Apache-2.0。リポジトリ作成日は 2026-02-09 10:11:37 UTC。候補取得時の GitHub pushed time は 2026-07-09 15:49:36 UTC、浅い clone で確認した main の最新 commit は 2026-07-09 15:47:38 UTC。最新 GitHub release は v13.7.0 で、公開時刻は 2026-07-08 07:58:08 UTC。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | Cranot/roam-code |
| 位置づけ | AI coding agent 向けの preflight、verify、evidence を持つローカル codebase intelligence layer |
| Stars | 495 |
| Forks | 47 |
| 主言語 | Python |
| ライセンス | Apache-2.0 |
| リポジトリ作成日 | 2026-02-09 10:11:37 UTC |
| 最近 push | 2026-07-09 15:49:36 UTC |
| 最新 main commit | 2026-07-09 15:47:38 UTC |
| 最新バージョン | v13.7.0 |
| リリース公開時刻 | 2026-07-08 07:58:08 UTC |
| 主な機能 | SQLite code graph、CLI、MCP server、preflight、verify、ChangeEvidence、secret scrubbing |
「まずリポジトリを理解する」をローカル手順にする
roam-code の README では、導入はかなり直線的だ。pip install "roam-code[mcp]" で入れ、対象リポジトリで roam init して索引を作り、roam health と roam preflight <symbol> で状態とリスクを見る。pipx install roam-code、uv tool install roam-code、source install、Docker も用意されている。
重要なのは、単に検索コマンドを増やすことではない。agent がよくやる「読みながら推測する」動きを、先にローカル code graph に落とす点だ。README は、デフォルトでは完全にローカルで動き、account、API key、cloud login を要求しないと説明している。private code、client code、offline repository を扱う人にとって、これは demo の見た目より大事だ。コードの事実をまず手元で索引し、model には必要な分だけ小さく明確な context を渡せる。
preflight も単なる grep ではない。README の例では、ある symbol について blast radius、影響する tests、complexity、coupling、convention check が出ている。実運用では例の数字をそのまま信じる必要はないが、この interface の形は実用的だ。agent が手を入れる前に、「この変更は危ないのか。危ないなら理由は何か」を聞ける。編集後に reviewer が問い詰めるより、ずっと自然な流れになる。
MCP tools の価値は task boundary にある
roam-code は MCP をかなり重く扱っている。README では現在 268 commands、243 MCP tools、そのうち default core preset は 16 tools と説明されている。src/roam/mcp-server-card.json には stdio、SSE、streamable HTTP などの transport と、code-intelligence、static-analysis、code-graph、security、attestation といった category も書かれている。
ただし、数の多さ自体が価値ではない。本当に大事なのは preset と mode boundary だ。どの task でも agent に full tools を渡すべきではない。README では MCP response の secret scrubbing、read_only、safe_edit、migration、autonomous_pr などの mode、decision receipt の記録が説明されている。この方向は、最近の agent tooling の痛点と合っている。tool が増えるほど、permission、evidence、audit を prompt ではなく protocol と runtime 側へ戻す必要がある。
Claude Code、Cursor、Continue、あるいは自前の MCP harness に tools をつなぐなら、roam-code はローカル codebase sensor に近い。「誰がこの関数を呼ぶか」「この file は何に依存しているか」「この変更の blast radius は何か」を答えられ、編集後には import、complexity、duplicate、secret leak なども確認できる。agent が急に賢くなるわけではないが、盲目的な編集は減らせる。
verify と evidence は単発の検索より面白い
多くの code search tool は、「関連ファイルを見つける」ことがゴールになりがちだ。roam-code でより面白いのは、編集前と編集後をつないでいる点である。
roam verify --auto は、触ったファイルに応じて check を選ぶ。Python の編集なら Python 関連の check が有効になり、source edit なら naming、duplicate、import、complexity、cycles、secret などを見る。--diff-only、--changed-lines、baseline、new-only といった option もあり、古いリポジトリの負債を全部爆発させるのではなく、新しい変更に範囲を絞る思想になっている。
README では ChangeEvidence も繰り返し出てくる。私の理解では、これは agent の作業を「見たと言っている」状態から、「証拠パケットを出せる」状態へ寄せるものだ。どの context を読んだのか、risk をどう見たのか、何を変更したのか、どの検証をしたのか、どこが未確認なのか。まだ若い考え方ではあるが、方向は正しい。今後 agent の PR を review するとき、diff と test result だけでなく、context usage と verification record も見るようになるはずだ。
向いている場面
ひとつめは、中規模以上のリポジトリでの局所変更だ。特定の関数や module を直す必要は分かっているが、影響範囲が見えない。agent に先に preflight を走らせ、読むべき files と走らせる tests を決めさせるほうが、grep から自由探索させるより安定する。
ふたつめは、agent PR の自動再確認である。roam-code は編集後の verify layer として、import hallucination、secret leak、complexity increase、duplicate code、局所的な architecture issue を早めに出せる。reviewer の代わりにはならないが、機械に向いたリスクを先に並べられる。
みっつめは、private codebase のローカル問答だ。デフォルトでローカル索引し、コードを第三者 service に送る前提ではないため、コードの外部送信に敏感な team が最初に試しやすい。もちろん、MCP client と model 側にどの context が渡るかは別途確認する必要がある。それでも、土台の code graph を cloud に置かなくてよいのは大きい。
よっつめは、agent workflow に evidence chain を足したい team だ。agent に issue 処理、refactor、PR 作成を任せ始めると、chat log だけでは足りない。structured evidence、signature、HMAC-linked ledger のような仕組みは、自然言語の要約より review と audit に向いている。
注意したいところ
第一に、プロジェクトの射程は広く、その分検証が必要だ。README には benchmark、evidence、security posture、tool count について多くの説明があるが、効果はリポジトリ、言語、agent によってかなり変わる。採用前には、自分たちのリポジトリで小さな A/B を行い、同じ種類の task について、roam-code ありなしで読んだ回数、失敗率、test selection、reviewer の負担を比べたい。
第二に、tool surface が広い。243 MCP tools は強力に見える一方で、permission design を雑にできないという意味でもある。まずは default core preset と read-only mode から始め、verify、safe edit、より高い権限の commands は段階的に開けるほうがよい。
第三に、v13.7.0 まで release は密だが、リポジトリ作成日は 2026-02-09 で、まだ新しいツールだ。production CI や強制 gate に入れる前に、indexing speed、false positive、failure behavior、cache directory、cross-platform path、チームの language stack coverage を確認したい。
第四に、GitHub の stars、forks、pushed time は継続的に変わる。ここに書いたのは 2026-07-10 の執筆時点で見えていた snapshot なので、後から読む場合は repository page を基準にしてほしい。
まとめ
roam-code の面白さは、AI coding の問題を「model にもっと context を渡す」だけにしないところにある。agent の周囲に、ローカルな code facts、task boundary、変更の evidence を置く。編集前に blast radius を見て、編集後に scoped verify を走らせ、必要なら reviewer に証拠を渡す。
すでに実際のリポジトリで coding agent を使っていて、「テストは通ったが reviewer がまだ不安」という問題に当たり始めているなら、Cranot/roam-code は一度試す価値がある。agent のコードが必ず merge 可能になるわけではない。それでも、「なぜこの変更を信頼できるのか」を、口約束ではなく検査できる tool output に近づけている。