calm-mcp

CALM — コーディングエージェントのライブネスマップ

コードベースをリアルタイムに可視化し、グラフで検証するマップです。AI コーディングエージェントは、手探りで grep するのではなく、全体を見渡して編集できます。

ベクトル類似度による推測ではなく、実際の呼び出しグラフを使用します。コンパイラーが利用できる場合は、エッジをコンパイラーで検証します。警告を読み飛ばされるだけではなく、書き込み経路そのものに厳格な安全ゲートを設けています。この README に記載された測定値は、現在の CALM スナップショットまたはベンチマーク成果物のいずれかに基づいています。リポジトリ固有の値は、コードベースの変化に応じて変わります。

初めての方へ。 クイックスタートなら、クローンも Rust ツールチェーンも不要で、1 分以内に使い始められます。Claude Code、VS Code、Cursor、Windsurf/Devin Desktop、Codex、Antigravity、JetBrainsに対応しています。このカテゴリのツールを比較していますか？ 実証が約束に勝るへ直接進んでください。内部構造を知りたいですか？ docs/architecture.mdでは、マルチティアインデックス作成、SCIP/LSP オーバーレイシステム、並行処理モデル、サニタイズ層を詳しく説明しています。

カバレッジ	24 言語を解析 · デフォルトで 13 言語の完全な呼び出しグラフに対応（ゼロ設定で 6 言語、デフォルトの tier0-5 バンドルでさらに 7 言語） · プロバイダー／ツールチェーンが利用可能な場合、12 言語に正式なコンパイラー検証済みのアップグレード経路を用意
安全性	公開された 5 つの MCP サーバーのベンチマークで、検証済みのハブシンボルに対する未確認の編集を拒否した唯一のもの
効率性	ファイルを単純に読み取るベースラインと比較した、タスク固有のトークン削減率です。ベンチマーク成果物を参照してください

---

問題

変更しようとしている関数を誰が呼び出しているのか知らずにコードを編集する AI エージェントは、遅かれ早かれ次のようなことをします。

• ほかの十数個のファイルから呼び出されている「デッドコード」を削除します。
• シグネチャを変更して、呼び出し箇所の半分を見落とします。
• 重要度が低いと思い込んでいたシンボルをリファクタリングし、ビルドを壊した後で、モジュール全体が依存するハブだったと気づきます。

これはどれも推論の失敗ではありません。可視性の失敗です。エージェントには、そもそもマップがなかったのです。マップを渡せば、推測する必要はなくなります。

「CALM」という名前の理由

多くのコーディングエージェントは、grep だけを使って不慣れなコードベースを扱う人と同じように作業します。何が何につながっているのか分からず、この関数に触れるとほかの 14 個に影響するかどうかも分かりません。それは自信ではなく、手早い推測です。

CALM は Coding Agent Liveness Map の略です。Liveness（ライブネス）なのは、マップが古いスナップショットのままにならないからです。ファイルシステムを監視し、ファイルの変更に応じて段階的に再インデックスを行い、各応答で現在の鮮度（scanning → parsing → building_edges → ready）を報告します。Map（マップ）なのは、単なるテキストインデックスを装ったものではなく、呼び出しエッジ、インポートエッジ、ハブ／コアネス指標を備えた実際のグラフだからです。地形を示す、リアルタイムで信頼できるマップをエージェントに渡せば、あわてて手探りすることはなくなります。落ち着いて作業できます。

得られるもの

• エージェントが、何が何に依存しているのかを推測しなくて済みます。 callers／callees／edit_context により、変更を反映する前に、既知のすべての呼び出し元を確認できます。tree-sitter による完全な呼び出しグラフは、13 言語に標準対応しています。Python、TypeScript、JavaScript、Java、Rust、Go は設定不要で使えます。さらに、デフォルトの tier0-5 文法バンドルにより、C、C++、C#、Ruby、PHP、Shell、R にも対応しています。ほかに 11 言語（Kotlin、Swift、Scala、Dart、Lua、Elixir、Haskell、OCaml、Zig、PowerShell、Groovy）も、オプトインのビルドフラグ --features lang-X を指定すると解析でき、合計 24 言語を解析できます（マルチティアインデックスを参照）。
• 変更を、気付かないうちに問題を引き起こすものにしません。 すべての書き込みは、正確な行範囲と照合してハッシュ検証され、ディスクに反映される前に構文チェックされます。ハブシンボルと呼び出し数の多いシンボルへの書き込みは、エージェントが呼び出し元を確認し、明示的に承認するまで確実に拒否されます。これは、実際の依存関係グラフを持つツールだけが適用できるポリシーであり、公開済みのほかの 4 つの稼働中 MCP サーバーとのベンチマークでは、これを適用するサーバーはほかにありませんでした。
• すべてのエッジに、信頼度が示されます。 呼び出しエッジには信頼度が付与されます（textual → inferred → resolved → formal）。コンパイラーでグラフを再確認できる場合は、CALM がその確認を行います。SCIP オーバーレイ（rust-analyzer、scip-go — 複数モジュールの go.work ワークスペースを含む — scip-python、scip-ruby など）や、ライブ LSP オーバーレイ（gopls、clangd）は、プロバイダー／ツールチェーンを利用できる場合、対応する 12 の言語連携全体で、推測に基づくエッジをコンパイラーで検証済みの確定情報にアップグレードできます。利用できないプロバイダーは、基本動作に影響を与えることなく処理から外れます。
• コードベースを自ら評価できます。 fitness_report は、ハブへの集中度、デッドコード、複雑さ、アーキテクチャ境界への違反を、単発の監査ではなく、照会可能で CI による強制も可能なシグナルに変えます。また、remember／recall によって、判断や注意点をセッションをまたいで利用できます。
• ほかのツールとうまく連携し、処理はマシン内にとどまります。 プロセス間の編集ロックと単一ライターのインデックス作成モデルにより、同じリポジトリを使う 2 つのエディターセッションが、互いの書き込みを破損したり、二重にインデックスを作成したりすることはありません。共有デーモンでは、セッション同士が互いの動作を確認することさえできます。インデックス作成、検索、編集のために、コードがマシンの外に送信されることはありません。デフォルトの埋め込みモデルはビルド時にバイナリに同梱され、重みが有効であれば実行時のネットワーク接続は不要です。重みを利用できない場合は、デフォルトで実行時の代替ダウンロードが許可されます。厳密なオフライン運用では、これを無効にできます。MIT ライセンスです。（オプトインによる例外がもう 1 つあります。--features otel を指定してビルドし、OTEL_EXPORTER_OTLP_ENDPOINT を設定すると、スパン属性（ファイルパス、シンボル名、ツール名、タイミング。ソースコード本体は含みません）が独自のコレクターにエクスポートされます。デフォルトでは無効です。docs/architecture.mdを参照し、https:// のコレクターのみを使用してください。）

CALM の適用領域

「AI エージェント向けのコードインテリジェンス」は、今や実際に確立されたカテゴリーです。Aider、Serena、Sourcegraph/Cody などのオープンソースの先駆者たちが、grep と善意に頼るよりも、実際のコード構造を備えたエージェントのほうがうまく機能することを証明してきました。CALM はその基盤を引き継ぎつつ、重心を変えています。このカテゴリーの大半のツールが読み取り経路に情報を与えるのに対し、つまり検索、ナビゲーション、コンテキストを改善するのに対し、CALM は書き込み経路も保護します。「これを呼び出しているのは誰か？」に答える同じグラフが、「確認するまでは変更できない」というルールも適用します。ハブや高リスクの編集では、編集前に最新のコンテキストを確認し、実際の呼び出し元に基づいて明示的に確認する必要があります。このポリシーはすべての編集に適用するよう拡張でき、書き込みはすべて、反映前にハッシュと構文が検証されます。

トレードオフは明確です。CALM がすぐに提供する完全な呼び出しグラフの対応言語は 13 言語であり、LSP 専用ツールの中には 40 言語以上に対応するものもあります。ただし、24 言語を解析でき、そのうち 12 言語はプロバイダーが利用可能な場合にコンパイラー検証済みのアップグレードパスを備えているため、その差は見た目ほど大きくありません。このトレードオフによって得られるのは、CALM 独自の特色が最もよく表れる機能です。信頼度付きのエッジ、編集前の厳格なゲート、そしてコードベース自身が健全性を評価する仕組みです。いずれも、自分で再現できる数値に裏付けられています（約束ではなく証拠）。

CALM は適していますか？

適しているケース： 質問に答えるだけでなく、コードを直接編集するエージェント · Tier-0／Tier-0.5 言語を使う単一リポジトリのコードベース · 同じリポジトリに対して複数の MCP クライアントを実行するプロジェクト（以下の対応クライアントを参照） · 埋め込み API に依存したくない、ローカルファーストのユーザー。

現時点で適していないケース： 複数リポジトリ／リポジトリ横断のエンタープライズ検索。そうした規模に特化したツール（Sourcegraph/Cody など）のほうが適しています · CALM が現在対応している 24 言語の tree-sitter セットに含まれない言語。

クイックスタート

対応クライアント — CALM は stdio に対応するあらゆる MCP クライアントで動作します。現在、以下のクライアント向けに設定済み、または手順をドキュメント化しています。

クライアント	モード	最速のインストール方法
Claude Code	CLI · Web · IDE	claude mcp add --transport stdio calm -- npx -y @eilodon/calm-mcp serve
VS Code	IDE（ネイティブ MCP／Copilot Agent モード）	code --add-mcp '{"name":"calm","command":"npx","args":["-y","@eilodon/calm-mcp","serve"]}'
Cursor	IDE · クラウド（Background Agent）	Cursor に追加 →
Windsurf / Devin Desktop	IDE · クラウド	~/.codeium/windsurf/mcp_config.json を編集します
Codex（OpenAI）	CLI · IDE	codex mcp add calm -- npx -y @eilodon/calm-mcp serve
Antigravity（Google）	CLI · IDE	~/.gemini/config/mcp_config.json を編集します
JetBrains AI Assistant	IDE	UI 設定から

上記すべてのクライアントの詳しい手順（グローバル設定が必要なクライアント向けの正確な設定例を含む）については、docs/mcp-client-setup.md をご覧ください。stdio の転送が届かない devcontainer／Codespace 内で実行していますか？ docs/http-transport.md をご覧ください（上級者向け、リモート開発専用、オプトイン方式、デフォルトではループバック接続）。

自分のプロジェクトで CALM を使う — クローンも Rust ツールチェーンも不要です。

{
  "mcpServers": {
    "calm": {
      "command": "npx",
      "args": ["-y", "@eilodon/calm-mcp", "serve"]
    }
  }
}

これをプロジェクトのルートにある .mcp.json（Claude Code／Cursor）または .vscode/mcp.json（VS Code では "mcpServers" の代わりにトップレベルの "servers" キーを使用します。それ以外の構造は同じです）に追加します。Claude Code プラグインを使う場合は、代わりに /plugin marketplace add Eilodon/CALM、続いて /plugin install calm@CALM を実行します。

npx ではなくネイティブバイナリを使いたい場合は、curl -fsSL https://raw.githubusercontent.com/Eilodon/CALM/main/scripts/install.sh | sh を実行してから、プロジェクト内で calm setup を実行します。同じ MCP 設定が自動的に書き込まれ、インストールしたバイナリが指定されます。代わりに calm setup --npx を追加すると、ポータブルな npx エントリーが書き込まれます（共有／コミット可能で、チームメイトや CI にバイナリは不要です）。再現可能なコールドインストールのため、デフォルトではこのバイナリと同じバージョンに固定されます。常に npm の最新リリースを解決するには、--track latest を指定してください。

CALM 自体を開発する場合（このリポジトリ）：

# 1. Build the binary
cargo build --release -p calm-cli

# 2. Initialize config for your project
calm init --project-root .

# 3. Build the index (embeds symbols too, if semantic search is enabled in config.json)
calm index --project-root .

# 4. Run the MCP server over stdio — incremental reindex kicks in automatically if an index already exists
calm serve --project-root .

このリポジトリには、Claude Code（.mcp.json）、Cursor（.cursor/mcp.json）、VS Code（.vscode/mcp.json）用の設定があらかじめ用意されています。いずれも scripts/mcp-launcher.sh を使用します。この共有ランチャーは、すでにビルド済みのバイナリを探し、該当する git タグを使用している場合はチェックサム検証済みのビルド済みリリースをダウンロードし、どれも利用できない場合はソースからビルドします。リポジトリをクローンすれば、そのまま動作します。事前の手動ビルドは不要です。

注： calm serve は起動時に .calm/ を .gitignore に自動追加するため、インデックスデータベースがコミットされることはありません。

例：エージェントの実際のワークフロー

agent: repo_overview()
  → current files/symbols and `indexing_phase=ready` are reported live

agent: "I need to change getUserByEmail"
  → locate("getUserByEmail")        # find the file + symbol metadata
  → source("getUserByEmail")        # read just the function body, not the whole file
  → edit_context("getUserByEmail")  # MANDATORY before any edit
      → the live caller count and risk assessment determine whether the agent reviews callers before touching the signature
  → edit_symbol("getUserByEmail", expected_hash=..., new_text=...)
      → risk_assessment=high, is_hub=true, no confirm:true → refused, with an explanation
  → edit_symbol(..., confirm=true, reason="checked getUserByToken, still returns the same shape")
      # reason must cite a real caller edit_context returned — writes for real, reindexes immediately
  → diff_impact(staged=true)        # verifies blast radius before commit

約束ではなく、証拠を示します

以下の表は、このチェックアウトで2026-08-12に観測されたCALMのスナップショットです。最新の状態を確認するには、repo_overview()とfitness_report()を再実行してください。リポジトリ固有の値は、コードベースの変化に応じて変わります。ベンチマーク比率はタスク固有であり、ベンチマーク成果物に記録されています。

指標	測定値
インデックス化されたコードベース	366ファイル、6,050シンボル — このリポジトリだけで15の言語ファミリーを確認
ハブ集中度（hub_pct）	7.38% — ハブシンボル271個（ゲート：≤ 20%）
デッドコード率（dead_code_pct、カバレッジ考慮）	5.04%（ゲート：≤ 10%）
ホットスポットリスク（hotspot_risk、変更頻度 × 複雑度、最悪のファイル）	0.90 — 現在ゲート（≤ 0.80）を超過しており、fitness_report()はFAILを報告します — 隠したり閾値を緩和したりせず、調査中です。fitness_report/calm fitness-checkを参照してください
エッジカバレッジ（edge_coverage_pct）	シンボルの72.39%に少なくとも1つの呼び出しエッジがあります（ゲート：≥ 60%）
高複雑度関数（high_complexity_pct）	2.8%（ゲート：≤ 15%）
アーキテクチャ適合度（avg_distance、Martin/OOD）	主系列からの平均距離0.28（ゲート：≤ 1.00）
境界が曖昧なシンボル（boundary_ambiguous_count）	0（ゲート：≤ 0）
アーキテクチャ境界違反（boundary_violations）	0（ゲート：≤ 0） — 以前ここで検出されたwatcher → toolsのインポートは、必要な共有トレイトRwLockExt/LockExtをtools/common.rsから独立したsync_extモジュールに移動して修正しました
設定のドリフト（config_drift_count）	0（ゲート：≤ 0） — 現在のドキュメント／設定パスの宣言は問題なく解決されます
素朴にファイルを読み込む場合と比べたトークン効率	ベンチマーク固有です。1つのタスクの比率をリポジトリ全体に当てはまる定数として扱わず、方法論を参照してください
テストスイート全体（デフォルト機能）	下記のテストを参照してください

競合ベンチマークの方法論と言語ごとの注意事項

稼働中の他の4つのMCPサーバーとのベンチマーク

benchmarks/b11_extended_competitor_ab/では、確立されたオープンソースのコードインテリジェンスMCPサーバー4つ — CodeGraph、Semble、grepai、Serena — をインストールして呼び出し、このリポジトリの分離されたGitワークツリーに対し、タスクごとに5回ずつ実行し、各タスクに正解判定基準を適用します。目的は順位表を作ることではなく、マーケティングページではなく、実際に稼働する先行事例と照らしてCALMの主張を検証することです。

実行結果は次のとおりです。呼び出し元の再現率と影響範囲のタスクでCALMは最高の結果に並び、5つのサーバーのうち唯一、編集前の安全ゲートでリスクのある未確認の編集を実際に拒否しました。他のサーバーは、事後にリスクを説明できるだけでした。すべての数値が良いとは限りません。あるトークン効率タスクでは、CALMの圧縮率は5つのうち最低でした。そこでの正確性も最高水準を維持しており、数値は測定結果のまま公開しています。これがこのプロジェクトのベンチマーク方針です。不利な結果も良好な結果と併せて公開します（benchmarks/README.md）。詳細な方法論、全タスク、ツールごとの生の数値は、ベンチマークのREADMEに掲載されています。

主張ではなく、測定に基づく言語対応状況

benchmarks/resolution/では、新たに追加された言語またはTier-0.5の言語19種を対象に、階層別の分布ベースライン（resolved / inferred / textual / ambiguousの内訳 — 正解判定基準なし、言語ごとに実際のOSSリポジトリ1つ）をそのままの形で実行・報告します。Kotlin（89.6%）とOCaml（86.3%）は、一般的な短いメソッド名の衝突により、主にambiguous階層に分類されます。Dartではシンボルは生成されますが、呼び出しエッジは生成されません。これはtree-sitterの文法に関する既知の制限であり、バグではありません。Tier-2の型推論が組み込まれているのは、現時点では元のTier-0言語のみです。言語ごとの完全な表は、ベンチマークのREADMEに掲載されています。

## CALM の仕組み

技術的な詳細はすべて docs/architecture.md にあります。すべての応答に suggested_next が含まれる理由や、リスクの高い手順を単に推奨するのではなく、厳格なゲートで制御する設計思想も説明されています。セクションごとの概要：

• マルチティアインデックス作成 — 13 言語はデフォルトで完全な呼び出しグラフに対応し、さらに 11 言語はオプトインの文法機能を有効にすると解析されます。合計 24 言語です。
• 信頼できる呼び出しグラフ — すべてのエッジには信頼度（resolved／inferred／formal／textual）がラベル付けされます。SCIP と LSP のオーバーレイは、プロバイダー／ツールチェーンが利用可能な場合、対応する 12 の統合を通じてエッジをコンパイラー品質の確かな情報に引き上げられます。利用できないプロバイダーは処理をスキップします。
• 実際に見つかる検索 — FTS5 とセマンティック埋め込みを Reciprocal Rank Fusion で統合し、インデクサーが解析しないファイルに対しても、ディスク上の実データを直接 grep／glob で検索します。
• 実際の安全策を備えた編集 — ハッシュ検証付き書き込み、ディスクに変更を加える前の構文検証、さらにハブ／高リスクのシンボルに対する 3 要素のゲート（最新の edit_context、confirm:true、根拠のある reason）を備えています。
• 並行性と信頼性 — 共有デーモン、プロセス間編集ロック、単一インスタンスのインデックス作成ロックにより、同じリポジトリで複数のエディターセッションを実行しても、作業が破損したり重複したりしません。
• コードベース自体による評価 — 11 の健全性指標、カバレッジを考慮したデッドコード検出、宣言されたアーキテクチャ境界、ドキュメントの乖離検出を備えています。
• 記憶し、行き詰まりも把握するエージェント — セッションをまたいで保持されるメモ、Git の共変更マイニング、行き詰まりループのシグナルを備えています。
• デフォルトで安全 — 認証情報のような内容は source／understand で伏せられ、プロンプトインジェクションのような内容にはフラグが付けられます。scan_text は外部テキストを対象とし、デフォルトではローカルファーストで動作し、明示的な埋め込みフォールバックも備えています。

クレートの構成

• crates/calm-core/ — インデックスエンジン：tree-sitter による解析、SQLite スキーマ、マルチティアリゾルバー（保守的 → 推論 → formal／Stack-Graphs、SCIP、または LSP）、グラフアルゴリズム（コアネス、ハブ検出）、FTS5／セマンティック検索、分析（ホットスポット、カバレッジ、codeowners、差分影響、デッドコード）、健全性指標、gitignore 管理。
• crates/calm-server/ — MCP サーバー（stdio または Unix ソケットデーモン経由の rmcp）。40 個のツールとインクリメンタルファイルウォッチャーを公開します。
• crates/calm-cli/ — CLI：calm init、calm index、calm serve、calm connect、calm setup、calm fitness-check、calm guard、calm doctor。

CLI リファレンス

calm init     --project-root .    # writes .calm/config.json with defaults
calm index    --project-root .    # one-shot full index (Scanning → Parsing → BuildingEdges → Ready)
                                 # also embeds symbols+chunks if semantic_search.enabled=true
calm serve    --project-root .    # MCP server over stdio + incremental reindex + file watcher
calm serve    --project-root . --listen unix:/path/to/daemon.sock   # run as a shared daemon (opt-in)
calm connect  --project-root .    # lightweight forwarder to an already-running daemon (opt-in, Unix)
calm serve    --project-root /project --db-path /data/index.db   # separate DB path (container deployment)
calm serve    --project-root . --preset orient   # register only the "orient" phase's tools
calm doctor   --project-root .    # validates config, DB (symbols/files/metrics history), git
calm setup    --project-root .    # writes/merges MCP config (.mcp.json/.cursor/.vscode) pointing at this binary
calm fitness-check --project-root .                             # CI gate, exits 1 on failure
calm fitness-check --project-root . --json                      # JSON output
calm fitness-check --project-root . --config thresholds.toml    # custom thresholds
calm guard    --project-root .    # pre-commit/CI gate on the staged diff, exits 1 if aggregate risk >= --fail-on (default: high)
calm guard    --project-root . --fail-on medium --json   # stricter threshold, machine-readable output
calm guard    --project-root . --base origin/main         # review this branch/PR against a base ref instead of the staged diff
calm guard    --project-root . --commits HEAD~3..HEAD      # raw commit range, passed straight through to git diff
calm value-report --project-root .                        # real counts from .calm/audit.log: risky edits blocked, risk distribution on what was applied
calm value-report --project-root . --json                 # machine-readable output
calm scip-run --project-root . --lang go        # force one SCIP provider to run now, bypassing refresh policy
calm scip-run --project-root .                  # --lang omitted = run every provider ("rust,go,python,javascript,java,csharp,php,ruby,c")
calm index    --project-root . --scip-file build/index.scip --sub-root services/api   # ingest a pre-built SCIP index (CI/sandboxed, no external indexer install needed)

AI エージェント向けの 40 個の MCP ツール

CLI プリセットでは、ワークフローのフェーズに応じて、orient、trace、edit、compound、full（デフォルト）でツールを絞り込めます。calm serve --preset または config.json の preset フィールドで指定します。または、ツールセット（モジュール）名からカスタムセットを組み合わせることもできます。例：--preset "trace,security" や --preset "full,-edit"（ツールセットの一覧は AGENTS.md を参照）。すべての応答には次の手順を示す suggested_next が含まれます。各ツールの詳細とワークフロー全体については、AGENTS.md を参照してください。

グループ	ツール
概要把握	repo_overview、hotspots、fitness_report（ヘルススナップショット — calm fitness-check と同じ指標をセッション中に照会できます）、indexing_status、test_gap_hotspots（中心性 × デッドコード／テストカバレッジの信頼度でシンボルをランク付けし、テスト作成の効果が最も高い箇所を示します）
検索	locate、search、file_overview
調査	source、symbol_info、understand、symbols_batch（複数の正確な qualified_name について、ソースと呼び出し元／呼び出し先を1回のラウンドトリップで取得します）
トレース	callers、callees（順序付きで上限を設定でき、ハブシンボルでは ETag キャッシュが可能です）、path、dependencies、reference_impact（呼び出しエッジ、インポートエッジ、テキスト検索を統合し、分類済みのリネーム／削除対象参照リストを1つ作成します。callers／dependencies のみの場合より範囲は広いものの、粒度は粗くなります）
編集	edit_context（編集前に必須）、edit_lines／edit_symbol（任意の内容を書き込む唯一のツール — ハッシュ検証済みです。ハブ／高リスク箇所への変更は、このセッション中に対象の正確なシンボルについて edit_context が実行され、confirm:true が渡され、reason に edit_context が返した実際の呼び出し元が記載されていない限り拒否されます）、format_files（標準入力経由の rustfmt のみ — 位置引数でファイルを指定できないため、rustfmt 独自のクレート全体にわたる mod ツリーの探索が実行され、独自の paths リスト外のファイルまで再フォーマットされることはありません。フォーマットではセマンティクスが変わらないため、confirm／edit_context のゲートはありません）、pattern_debt_register／pattern_debt_status（search(kind="similar") を通じて qualified_name で重複するバグパターンを記録し、後で open／resolved／anchor_lost の状態を再確認します）、diff_impact（コミット前に必須） — edit_context と diff_impact は Claude Code ではフックによって強制されます（.claude/hooks/calm-nudge.sh を参照）。他の MCP クライアントでは、session_context の pending_diff_impact が同等のシグナルになります
変更（権限）	plan_change／review_change — 編集ゲートを介した、レビュー可能な変更用ファサードです。plan_change は、これから行うこととその理由を示す ChangeIntent を、永続的でレビュー可能な記録として宣言します。review_change は、approved:true（クライアント自身による表明で、低リスク／中リスクの場合にのみ十分です）であれば署名付きの ReviewAuthority を発行します。実際の PolicyEngine／RiskVector による評価で独立した人間のレビューが必要と判定された場合は、発行を拒否します。edit_lines／edit_symbol で権限を使用する際には、発行時だけでなく、その時点で改めて検証されます
Txn（管理）	batch_status（呼び出し元が指定した複数の edit_lines／edit_symbol／format_files 呼び出しの tx_id リストを1つのビューに集約し、状態別の件数と失敗の有無を示します）、edit_transaction_status、maintenance_status、retry_maintenance、repair_consistency、verify_change（WS-6 の最初の段階：オプトインで検証された編集について、オンデマンドで cargo check を実行します） — edit_lines／format_files が新たに書き込み先とする WS-1 の永続的な編集トランザクションジャーナルに関する、トランザクション／メンテナンス・アウトボックスの診断です。独立した txn ツールセットに登録され、edit プリセットに含まれます（orient／trace／compound には含まれません）

| 復旧 | session_context、remember、recall | | 高度な操作 | scip_refresh、lsp_refresh — 自動更新ポリシーを迂回して、SCIP／LSP プロバイダーの一部またはすべてを今すぐ強制的に実行します。scan_text — 任意のテキスト（WebFetch／WebSearch の結果、サブエージェントのレポート、貼り付けたコンテンツ）に対して、source／understand が使用するものと同じプロンプトインジェクション／認証情報のヒューリスティクスを実行します。ローカルかつオフラインで動作し、ホスト型 LLM の安全性分類器には依存しません。set_toolset — サーバーを再起動せずに、このセッションが実行時に公開するツールを絞り込むか、リセットします（安全性の最低限の構成である orient+guardrails+recover+edit は常に維持されます）。4つすべてが利用できるのは full プリセットのみです。上記4つのワークフローフェーズのプリセットには含まれません。これは意図的に用意された手動／まれな使用向けの回避手段であり、デフォルトのフローに含まれるステップではありません |

MCP プロンプト — スラッシュコマンドとしてパッケージ化されたワークフロー

上記の tools とは異なり、MCP プロンプト（prompts/list、prompts/get）は、繰り返し使うワークフロー用の、そのまま使える単一の指示メッセージを返します。MCP クライアントはこれらをスラッシュコマンドとして表示します。

プロンプト	引数	パッケージ化されたワークフロー
review_symbol	symbol	locate → source → edit_context（必須）→ 何かに手を加える前にリスクを要約
debug_symbol	symbol	understand → callers(max_depth=3) → test_files／dead_code_confidence を確認
onboard_area	path	repo_overview → file_overview／dependencies → そのパスに絞った hotspots
review_pr	range	diff_impact(commits=range) → hotspots（重複を確認）→ fitness_report → マージ前にリスクをまとめて要約
calm_workflow	(なし)	Stage 1～8 のツールワークフロー全体を引数なしで案内します。AGENTS.md を自動で読み込まないクライアントや、セッション途中の再確認に使えます。

1 行で導入できる CI：CALM Guard GitHub Action

action.yml は calm index と calm guard を再利用可能な複合アクションとしてラップします。MCP クライアントを使わず、すべての PR で影響範囲のレビューだけを実行したいリポジトリに、1 行で導入できます。

- uses: Eilodon/CALM@main
  with:
    fail-on: high   # default; "low"/"medium" also accepted

pull_request イベントでは、PR のベースブランチを自動検出し（デフォルトの浅いチェックアウトではベースブランチが取得されていないため、その参照だけを取得します）、マージベースを基準にした範囲をレビューします。通常の push では before..after をレビューします。どちらの場合も、calm guard 自体の --base／--commits フラグに対応する base／commits 入力で上書きできます（上記の CLI リファレンス を参照）。自動検出で対応できないもの（workflow_dispatch、マージキューイベントなど）では、いずれかを明示的に設定してください。ランナーからアクセス可能な、npm に公開済みの @eilodon/calm-mcp リリースが必要です。それ以外にインストールするものはありません。

Fitness check — CI ゲート

.github/workflows/ci.yml の fitness-check ジョブで、すべての push／PR に対して実際に実行します。まず calm index を実行します（新しいチェックアウトにはまだ .calm/index.db がないためです）。次に calm fitness-check --project-root . --config thresholds.toml を実行します。--config フラグは省略できません。これがない場合、[[boundaries]] と [config_drift] はエラーにならず、「ルールが宣言されていないもの」として暗黙に扱われます。実際にデフォルト値があるのは数値のしきい値のみです。

calm fitness-check は、thresholds.toml で宣言されたしきい値に対して 11 個のメトリクスを測定します。

メトリクス	測定内容	実効しきい値
hub_count	ハブとして分類されたシンボルの数	≤ 1000
hub_pct	ハブであるシンボルの割合（スケール不変）	≤ 20.0%
avg_coreness	グラフ全体の k-core コアネスの平均	≤ 15.0
dead_code_pct	デッドコード信頼度が「高」のシンボルの割合	≤ 10%
hotspot_risk	コードベース内で最も高いホットスポットスコア	このリポジトリでは ≤ 0.80（thresholds.toml による上書き。組み込みのデフォルトは ≤ 0.75）
edge_coverage_pct	呼び出しエッジが 1 つ以上あるシンボルの割合	≥ 60%
high_complexity_pct	McCabe 循環的複雑度が 10 を超える関数／メソッドの割合（AST ベース。Tier-0.5 言語では常に複雑度 1 を報告）	≤ 15.0%
avg_distance	Martin/OOD における主系列からの平均距離。各ファイルの抽象度が、その不安定度（Ca/Ce）から導かれる理想値からどれだけ離れているかを示します	≤ 1.00
boundary_violations	宣言された [[boundaries]] ルールに違反する import_edges の数	≤ 0
boundary_ambiguous_count	境界行が隣接するシンボルと共有され、曖昧になっているシンボルの数。解消するまで、これらに対する edit_symbol の置換は拒否されます	≤ 0
config_drift_count	実在しない場所を指している、ドキュメントのファイルパス参照の数（[config_drift].doc_paths で宣言）	≤ 0

上記で特記されていない限り、この表では組み込みの数値デフォルトを使用します。このリポジトリにコミットされている thresholds.toml が、CI で適用されるポリシーです。calm fitness-check を実行するたびに、メトリクスも DB にスナップショットとして保存されるため、edit_context で推移（前日との差分）を確認できます。

アーキテクチャの境界 — [[boundaries]]

「モジュール A はモジュール B を直接インポートしてはならない」というルールを、thresholds.toml の [thresholds] と同じファイルに宣言します。パスのプレフィックスで照合され、glob／正規表現は使いません。これは、Rust 自体のクレート／モジュール境界ではすでに強制されていないレイヤー構造を対象とします。「calm-core は calm-server をインポートしてはならない」と宣言しても、Cargo の依存関係グラフによって構造上すでに不可能なため、何も起こりません。

[[boundaries]]
from = "crates/calm-core/src/indexer/"
to = "crates/calm-core/src/analysis/"
reason = "indexer (extraction) must stay upstream of analysis (dead-code, hotspots, fitness) — not the other way around"

calm fitness-check は、--json モード以外では、違反ごとに具体的な内容（実際の from/to パス、ルール、理由）を報告します。デフォルトの max_boundary_violations = 0 により、わざわざ宣言したルールは、実際に守るルールになります。

このリポジトリの thresholds.toml では、現在 2 つのルールを宣言しています。上記のルールに加え、crates/calm-server/src/watcher.rs → crates/calm-server/src/tools/（「バックグラウンドの再インデックス／監視ループは、それが独立して実行する MCP ツールハンドラーレイヤーに依存してはならない」）です。どちらも違反は 0 件です。

デプロイ

• .github/workflows/release.yml による cargo build --release で、静的バイナリ（Linux では musl）をビルドします。5 ターゲットのマトリックスを使用し、各アセットに SHA256SUMS とビルド来歴のアテステーションを付与します。対象は x86_64-unknown-linux-musl、aarch64-unknown-linux-musl、aarch64-apple-darwin、x86_64-apple-darwin、x86_64-pc-windows-msvc です。対応ターゲットでチェックアウト時（またはインストール時）に一致する git タグが指定されていれば、scripts/mcp-launcher.sh／scripts/install.sh が該当プラットフォームのビルドを自動的にダウンロードし、チェックサムを検証します。タグがない場合、オフラインの場合、または未対応プラットフォームの場合は、既存のバイナリまたはソースからのビルドにフォールバックします。
• Containerfile はマルチステージ構成（rust:alpine → scratch）で、必要なのは単一の静的バイナリのみです。実行時のイメージは不要で、git タグのプッシュごとに ghcr.io/eilodon/calm-mcp に公開されます（バージョンタグと latest）。
• compose.yaml には、セキュリティを強化した設定例（read_only、cap_drop: ALL、no-new-privileges、pids_limit: 64、mem_limit: 256m）が含まれています。
• デフォルトの埋め込みモデルの重みは、include_bytes! によってバイナリに同梱されます。build.rs::ensure_embedding_weights は Hugging Face Hub から crates/calm-core/assets/potion-code-16m/*.safetensors を取得し、コンパイル時に一度だけチェックサムを検証します。そのため、重みが有効であれば、通常の cargo build／リリースバイナリの実行時にネットワークアクセスは不要です。Git LFS は使用していません（このリポジトリには LFS コンテンツは一切ありません）。

ビルド時の取得に失敗した場合（オフラインビルドなど）の動作

cargo build は引き続き正常にコンパイルされます。ビルドに失敗する代わりに、build.rs が実際の重みの代わりに小さなプレースホルダースタブを書き込みます。このスタブを実行時に読み込むと失敗します（「failed to parse safetensors」）。そのため、Embedder::load は自動的に同じモデルを Hugging Face Hub から一度だけダウンロードします（その後、ローカルにキャッシュされます。デフォルト設定ではこのフォールバックが許可されていますが、semantic_search.allow_network_fallback = false にすると実行時は完全にオフラインになります）。このフォールバックが無効になっている場合、またはフォールバックも利用できない場合、indexing_status は embeddings_status: "failed" を報告し、search(kind="semantic"/"hybrid") は FTS のみの検索に切り替わります。クラッシュすることはなく、モデルが利用可能になるまで、再ビルドまたは再実行してもセマンティック検索は行われません。

## ランタイムとトランスポート

• デフォルトのモードは MCP stdio です。 Unix では、ランチャーの追加引数なしで起動すると、ランチャーは共有 Unix デーモンを使用します。カスタムの起動方法、CI、Windows では、単一プロセスの calm serve を使用できます。
• HTTP はオプトインです。 calm serve --http は、デフォルトで 127.0.0.1:8787 にバインドします。ループバック以外に公開するには、--allow-remote と、Bearer トークンとして送信する空でない CALM_HTTP_TOKEN が必要です。
• リモート HTTP は読み取り専用です。 CALM は有効なプリセットを remote-safe に強制します。これは、手動管理のリストではなくツールルーター自体から算出される、read_only_hint = true を宣言したすべてのツールを対象とするため、新たに追加された状態変更ツールが暗黙のうちに対象から漏れることはありません。TLS はリバースプロキシで終端してください。組み込みの HTTP トランスポートは多層防御としてリクエスト本文のサイズと同時リクエスト数に上限を設けていますが、実際のレート制限や IP ごとの DoS 対策はないため、信頼できないネットワークに直接公開しないでください。

テスト

cargo test --workspace                        # unit + integration (embeddings is a default feature, included)
cargo test --test parity_test test_formal_edges   # Stack Graphs regression corpus

11 個の CI ジョブがすべての PR で実行されます（手作業で数えたものではなく、.github/workflows/ci.yml 自体のジョブ一覧で確認済みです）。verify（fmt/clippy/test/audit）、calm-guard-dogfood（このリポジトリ自身の PR に対して action.yml をドッグフード実行します。新しい間は continue-on-error: true のシャドーモードです）、stack-graphs-corpus（formal-resolver の同等性）、txn-crash-injection（WS-1 のクラッシュ注入スイート。到達可能なすべての TxState 遷移でプロセスを終了させる、実際の SIGKILL）、embeddings（embeddings 機能を有効にして clippy + test）、no-stack-graphs-formal（stack-graphs-formal を無効にして clippy + test。この機能ゲートがコンパイルする resolver::formal スタブを対象とする唯一の CI カバレッジ）、all-languages（解析対象の全 24 言語にわたるフィクスチャーリポジトリのインデックス作成と、lsp-overlay）、js-client-interop（Rust 自体のクライアントだけでなく、実際の JS MCP SDK クライアントを使ってツールスキーマを照合）、otel-http-features（otel/http 機能を有効にして clippy + test を実行し、opentelemetry コアのバージョン不整合も検出）、fitness-check（このリポジトリ自体のインデックスに対して calm fitness-check を実行します。下記の Fitness check を参照）、status-drift（docs/status.generated.md が古い場合、手書きドキュメントのツール数がその内容と異なる場合、またはベンチマークの claims registry の構造に一貫性がない場合にビルドを失敗させます）。

ワークスペースには 1,000 件を超えるテストがあります。合否の判断には、最新の CI verify ジョブを正式な基準としてください。#[ignore] が付いた少数の実バイナリ統合テスト（例：rust-analyzer/scip-go/scip-java）では、すべての環境にインストールされているわけではない外部ツールが必要です。

関連資料

• docs/architecture.md — マルチティアインデックス、SCIP/LSPオーバーレイ、検索の内部構造、編集セーフティネット、並行処理、自己評価、メモリ、サニタイズ、そしてそれらすべてを支える設計思想について、技術的に詳しく解説しています。
• docs/comparison.md — このカテゴリの他のツールと比較し、方法論を優先して位置づけを説明しています。
• docs/what-external-users-get.md — このリポジトリを開発用にチェックアウトした場合とは異なる、npx/npm/MCP-Registry のインストールで得られるものを正確に説明しています。インストールと配布の仕組み、ツールとツールセットの詳細、編集の安全性レイヤー、言語の対応範囲、外部には決して配布されないものを取り上げています。
• docs/ — 上記の docs/architecture.md では扱っていない、リゾルバーの内部構造、移行計画、その他の設計メモを掲載しています。
• docs/adr/ — 個々のアーキテクチャ決定記録（Stack Graphs の対象範囲、正式なリゾルバー方式、LSP による任意の信頼性向上、デーモンとフォワーダーによる並行処理モデル）を掲載しています。
• docs/mcp-client-setup.md — Windsurf/Devin Desktop や Codex のグローバル設定を含む、すべての MCP クライアントのインストール方法を詳しく説明しています。
• docs/http-transport.md — オプトイン方式のリモート/HTTP トランスポート（calm serve --http）について説明しています。デフォルトではループバックにバインドされること、フェイルクローズ方式の --allow-remote とトークンが必要なこと、リモート公開時に読み取り専用プリセットが強制される理由、TLS/リバースプロキシが前提となることを取り上げています。
• AGENTS.md — このプロジェクト独自のエージェントが従う、ツールごとのワークフローガイドをすべて掲載しています。
• KNOWN_LIMITATIONS.md — CALM がまだ対応していないこと（単一言語でのサンドボックスなしの検証、複数ファイルにまたがる変更セット、参照への影響を調べるツールがないこと、変更種別のシグナルがないリスク分類など）を率直に列挙し、それぞれを中途半端に実装せず、意図的に先送りしている理由を説明しています。
• benchmarks/ — この README のベンチマークに関する主張を裏付ける測定スイートと、その他の測定結果を掲載しています。b2_call_graph_quality/（SCIP オラクルに対する適合率／再現率）、b3_search_quality/（ハイブリッド RRF、FTS のみ、通常の grep を比較した NDCG@10）、b4_token_efficiency/（タスクごとの素朴なベースラインに対するトークンコスト）、b6_tool_call_efficiency/（素朴な複数回呼び出しと 1 回の MCP 呼び出しの往復回数）、b7_task_correctness/（6 つの言語コーパス（fd/Rust、flask/Python、express/JS、zod/TS、gin/Go、spring-petclinic/Java）にまたがる実際の名前変更リファクタリングを、LLM の判定ではなく独立した合否オラクルで検証）、b11_extended_competitor_ab/（自己申告の数値ではなく、稼働中の他の MCP サーバー 4 つに対する実際の呼び出し）、b12_tier1_tier2_tool_correctness/（外部の OSS リポジトリ 6 つに対して JSON-RPC 経由で 9 つのツールを実際に実行し、正規表現／git grep と照合して正解を確認）、resolution/（実際の OSS リポジトリ 19 個を対象とした、言語ごとに 1 つのティア分布ベースライン）を掲載しています。芳しくない結果も良好な結果と並べて意図的に公開しています。その方針は benchmarks/README.md に記載されています。

ライセンス

MIT