Cranot/roam-code

Local codebase intelligence CLI + MCP server for AI coding agents: SQLite code graph, 28 languages, 287 commands, 246 MCP tools, change-safety gates, audit evidence, zero API keys.

📚 roam‑code とは何か

roam‑code は、コードエージェント（LLM駆動のコード生成ツール）向けに設計された、Pythonベースのローカル実行型静的解析ツールキットです。リポジトリ内のシンボル（関数、クラス、インポート、それらの関係）を検索可能なマップに構築し、エージェントが「この関数を呼び出しているのは誰ですか？」や「この変更が影響するテストはどれですか？」といった質問を、すべてのファイルを読むことなく行えるようにします。

このツールはリモートモデル呼び出しを行いません。すべての処理はあなたのマシン上で行われます。CLI（roam）として提供され、オプションでMCP（Model-Control-Protocol）サーバーも提供され、エージェントが標準的なツール呼び出しインターフェースで通信できるようになります。

🔧 コア機能（READMEに記載）

機能	機能の内容	使用方法
インデックス作成 / `roam init`	リポジトリ全体を解析し、28言語、287コマンド、246MCPツールをカバーするシンボルグラフを構築します。	リポジトリのルートで `roam init`（または軽量ビルド用に `roam index`）を実行します。
事前チェック（`roam preflight <symbol>`）	変更の影響範囲（影響を受けるシンボル／ファイル数）を推定し、関連テスト、複雑度、結合度などを報告します。	`roam preflight open_db` – 実際の数値を含むリスク評価を返します。
ヘルスサマリー（`roam health`）	コード構造、検出結果、全体的な「ヘルススコア」の概要を提供します。	インデックス作成後に `roam health` を実行します。
検索（`roam search <name>`）	インデックス済みグラフ内で名前でシンボルを検索します。	`roam search handleSave` を実行します。
検証（`roam verify …`）	変更されたファイルに対して静的チェックのセットを実行：命名規則、インポートの有効性、複雑度、シークレット漏洩、イディオムパターン警告など。	`roam verify --auto`（変更されたファイルに適したチェックを自動選択）またはより細かいフラグを使用。
MCPサーバー（`roam-code[mcp]`）	ネットワークソケット経由で同じクエリを公開し、LLMベースのエージェントがツールとして呼び出せるようにします。	`pip install "roam-code[mcp]"` でインストールし、サーバーを起動。エージェントはMCP経由で `roam` コマンドを呼び出せます。
Claude Code用フック（`roam hooks claude`）	Claude Codeのプロンプトに実行前コンテキスト（呼び出し元、最近の変更）を自動挿入し、モデル終了後に結果を検証します。	`roam hooks claude --write` で有効化、`--uninstall` で削除。
Roam Guard	PRゲートとして動作し、実行されたチェック、その結果を記録し、重大な発見が見つかった場合にマージをブロックできます。	CIで `roam verify --auto` を使用。特定の深刻度で失敗するように設定可能。
パフォーマンス	インデックス作成は一度限りのコスト。以降のリフレッシュは高速です。ベンチマーク（2026年5月～7月）では、ナビゲーション系クエリでLLMのターン数が最大80％削減され、トークン数・コストも大幅に削減されました。	READMEの詳細なベンチマーク表を参照してください。

🚀 通常の導入方法

リポジトリに追加 – プロジェクトの仮想環境内で pip install "roam-code[mcp]" を実行。
インデックス作成 – roam init を実行（大規模コードベースでは初回で数分かかる場合あり）。
エージェントを接続 – MCPサーバーまたはClaude固有のフックを有効化し、LLMが推論中に roam データをリクエストできるようにします。
CIでチェック実行 – roam verify --auto（またはカスタムチェックセット）を実行し、マージ前に「ゲート」を設けます。
反復 – 変更後、roam preflight <symbol> を実行してコミット前に影響範囲を確認します。

📊 AI支援開発における重要性

ローカル、プライバシー保護 – APIキーもテレメトリも不要。分析はオンプレミスで完結。
エージェント中心 – LLMが直接利用可能な構造化されたシンボルレベルのコンテキストを提供し、通常必要な「検索→ファイル開く」ステップを削減。
言語非依存 – 28言語をサポートし、ポリグロットモノレポに有用。
ゲートキーピング – CIパイプラインの一部として、リスクの高い変更のマージを防ぎ、人間のコードレビューを補完。

📦 クイックスタート（4つのコマンド）

pip install "roam-code[mcp]"   # CLI + オプションのMCPサーバー
cd /path/to/your/repo
roam init                       # インデックスと設定の構築
roam health                     # ヘルススナップショットを確認
roam preflight <symbol>         # 編集前にリスクを評価

TL;DR

roam‑code は、コードベースを検索可能なシンボルとその関係のグラフに変換する、無料でオープンソースの静的解析エンジンです。LLMベースのコードエージェントが正確で低トークンの質問を投げかけられ、CIで安全ゲートを強制できる一方、ソースコードをマシン外に送信することもありません。