AIDive

動画パック

Claude Code mod: 出典付きの結論、計測結果、月曜のチェックリスト

9 分で読めます

TL;DR

  • 10個のmodのうち3つを残す: collision-guard、model-router、auto-handoff。いずれもヘッドレスの読み取りタスクで計測上のオーバーヘッドはほぼゼロで、名前を挙げられる課題を解決している。
  • next-stepsは削除する。条件を満たす回答のたびにセッションをforkし、今回の計測では1ターンあたり出力トークン+250、+2850 msかかった。提案を描画しない画面でも同じだった。
  • cache-keeper(+1589 ms、モデルへのpingに課金)、recording-mode(マスクするのは表示だけで保存済みの履歴ではない)、session-bookmarks(モデル呼び出し、プロセス実行、ファイル書き込みができるブックマーク)も削除する。
  • goal-meter、repo-heatmap、flight-recorderは、見た目が欲しい場合を除いて削除する。コストはほぼゼロだが、計測できる利点もなかった。
  • guard系のmodはデフォルトでfail openになる。.catchハンドラがないと、throwしたguardはスキップされ、コマンドは実行される。
  • modはサンドボックス化されていない。インストール前にclaude plugin validateの出力を読むこと。

計測から分かること

話題性と規模。リリースのツイートは、2026-10-03にスナップショットを取った時点で4,138,918ビュー、20,021いいね、13,440ブックマークだった s11。コミュニティのカタログには、873の候補リポジトリに1018個のmodが載っている。スキャンは2026-10-03、Claude Code 2.1.288に対して実施した s9。

modはイベントにフックする関数だ。イベントの前、後、代わり、またはイベントを包む形で実行できる s1。modにはClaude Code v2.1.287以降が必要で、デフォルトで有効になっている s2。

まずセキュリティ。Anthropic自身の表現はこうだ。"Mods run with the same access to your machine as Claude Code itself. They aren't sandboxed" s1。modが起動したプロセスは、サンドボックスを有効にしていてもサンドボックスの外で動く s2。Read(.env)を拒否していても、modは$.fs.readでそのファイルを読めるし、読めるプログラムを起動することもできる s6。カタログのスキャンでは、409個のmodがホストのプロセスを実行し、167個がファイルを書き込み、150個がネットワークに接続し、28個はこのバージョンでvalidateに失敗した s9。

売り文句と実際の権限範囲。静的監査では、session-bookmarksは$.model.complete、$.process.run、$.fs.writeを呼んでおり、ブックマーク機能のために一式の中で最も広い権限を持っていた。next-stepsは最も小さく、fsもprocessもenvも使わない。この監査には、claude plugin validateが出力するcalls:とenv reads:の行を使った s6。

看板のmodにはターンごとのコストがある。next-stepsはturn.completeで$.model.forkを使ってセッションをforkし、READMEにはforkが"costs about one short reply"とある s10。提案が描画されるのはターミナルだけで、他の画面には何も表示されない s10。forkを無効にするオプションはない。ヘッドレスでの計測では、出力トークンが+250、時間が+2850 ms増え、何も表示されないのにforkの分はセッションの使用量に計上された s10。

ドキュメントに書かれた上限。フックの実行時間は1イベントあたり10秒、$.fsの読み書きは1ファイルあたり4 MiB、$.storeはJSON合計4 MiBまでだ s3。

guardはfail openになる。ドキュメントによると、.catchハンドラのないフックがthrowしたりタイムアウトしたり、誤った形を返したりした場合はスキップされ、代わりに次のハンドラが実行される s7。これは再現できた。throwする.catchなしのBash guardでは、touch ./marker-failopen.txtがファイルを作成した。同じguardに{deny}を返す.catchを付けるとファイルは作られなかった。ある現場のレポートでは、guardが有効で動作中なのに何もしておらず、plugin listには"enabled"と表示されたままだった s8。

2.1.288には未解決のバグがある。await next(e)の後で返したdenyがツールを止めず、モデルには書き込み失敗と伝えられたのに、ファイルは3回中3回書き込まれた s5。

modとsettingsのフックの比較。settingsのフックは呼び出しごとにプロセスを起動する。起動コストを計測すると、trueバイナリで2.2 ms、bash -c 'exit 0'で8.3 ms、python3 -c 'pass'で26.1 ms、node -e ''で43.1 msだった。週5,993回のツール呼び出しでは、nodeのフックが258 sかかる。プロセス内で動くmodにこのコストはない。すでにイベントをブロック、許可、ログ記録するスクリプトがあるなら、ドキュメントはsettingsのフックを勧めている s2。あるマイグレーションの報告では、27個のシェルフックが5個のmodになった s8。

マスキングは表示だけ。recording-modeが書き換えるのはui.renderが描画する内容だけだ。~/.claude/history.jsonlには入力したままのプロンプトが残り、あるテスターは自分のcanary文字列がトランスクリプトのqueue-operationエントリに7回見つかったと報告している s5。

modが動かない場所。ヘッドレスのclaude -pとAgent SDKはフックを実行するが何も描画しない。Desktop WSLのセッションはどちらも実行しない s2。

カタログの信頼性。あるテスターは、ボタンが$.process.runでプログラムを起動し、ホームディレクトリにファイルを書き込むmodを公開した。警告なしに、他のmodと同じようにインストールできた s5。これは自分で公開した概念実証であり、実際に確認された攻撃ではない。

計測結果

対象データ: 実際の環境の直近7日間。85セッション、4プロジェクト、ユーザープロンプト882件、アシスタントのターン11,010回、ツール呼び出し5,993回。ベンチマークはClaude Code 2.1.288(macOS)で実行した。

config dur ms Δdur out tok Δout task ok
baseline 3980 0 247 0 3/3
next-steps 6830 +2850 497 +250 3/3
cache-keeper 5569 +1589 367 +120 3/3
recording-mode 8240 +4260* 598 +351* 3/3
goal-meter 3722 -258 244 -3 3/3
collision-guard 4565 +585 376 +129* 3/3
repo-heatmap 4119 +139 257 +10 3/3
flight-recorder 3949 -31 261 +14 3/3
model-router 3698 -282 238 -9 3/3
session-bookmarks 4152 +172 235 -12 3/3
auto-handoff 4051 +71 248 +1 3/3

*の付いた行は、回答のばらつきによる可能性が高い。recording-modeは計測中オフで、オフの間は何も注入しない。

再実行の手順:

  1. modを1つずつインストールし、claude plugin validateを通ることを確認する。
  2. 同じ読み取り専用タスクを、haikuでclaude -pによりヘッドレス実行する。configごとに3回繰り返し、所要時間と出力トークンの中央値を取る。
  3. 引用するのは所要時間と出力トークンの差分だけにする。USDのコストはconfig間のキャッシュ順序で変わるので無視する。
  4. 起動コストは、各フック本体を30回起動した時間の中央値を取り、週のツール呼び出し回数を掛ける。

月曜にやること

  • インストール済みのすべてのmodにclaude plugin validateを実行し、calls:とenv reads:の行を読む。
  • 権限範囲(プロセス、fs書き込み、モデル呼び出し)が仕事に見合わないmodは無効にする。
  • ヘッドレス実行、VS Codeパネル、SDKが中心なら、next-stepsを無効にする。それらでは提案が描画されない。
  • 頼っているすべてのguard modに、{ deny: ... }を返す.catchハンドラを追加する。
  • 各guardがfail closedであることを確認する。わざとthrowさせ、マーカーファイルを作るコマンドを実行して、ファイルができないことを確かめる。
  • ~/.claude/history.jsonlやトランスクリプトに秘密が残らないことを、マスキングmodに頼らない。両方をディスク上で確認する。
  • nodeやpythonを使う呼び出しごとのシェルフックは、週のツール呼び出し数で起動コストが積み上がるなら、プロセス内のmodかコンパイル済みバイナリに置き換える。
  • オフスイッチを覚えておく: /pluginで1つのmodを無効化、1セッションだけなら--safe-mode、全体なら~/.claude/settings.jsonの"disableAllHooks": true。

さらに読む

  • 自分でmodを作る: 約80行のmodを作るハンズオン解説。重要な落とし穴も載っている(モジュールレベルの状態はホットリロードでリセットされるので、データは$.stateに置く) s4。
  • mod、フック、スキル、settingsのどれにするかは自分の履歴から決める: ある実践者は、まずセッションログから繰り返し起きる問題を掘り出すことを勧めている s12。
  • guardを書く前に、イベントの全一覧と上限を読む s3。
  • 組織全体の管理はここでは扱わない。個人開発者向けの要点は1つだけ。sec-defaultは、マシンにmanaged settingsがあるか、TeamまたはEnterpriseプランでサインインしているときに読み込まれ、他の制限は追加しない s6。
  • 設計の経緯、2.1.288で修正されたworktree分離のバグ、ランタイムの内部構造は、公開スレッドにある s5。
  • Anthropicのサンプルmod(token-weather、blast-radius、replay-theater)は、サポートなしの共有として掲載されている s2。

情報源

FAQ

modはサンドボックス化されている?

いいえ。Anthropicによれば、modはClaude Code自身と同じ権限でマシンにアクセスする s1。modが起動したプログラムもサンドボックスの外で動く s2。

guard modがクラッシュしたらどうなる?

.catchハンドラがなければスキップされ、コマンドは実行される s7。{ deny: ... }を返す.catchを追加して、fail closedにすること。

modはトークンを消費する?

モデルを呼び出す場合だけだ。今回動かした10個のうち、計測できるコストが出たのはnext-stepsとcache-keeperで、他は今回の計測では堅実なオーバーヘッドは見られなかった。

modをすばやく無効にするには?

/pluginで1つ無効にする、--safe-modeでセッションを開始する、または~/.claude/settings.jsonで"disableAllHooks": trueを設定する s2。どれも組み込みのmodは止められない。

インストール前にmodの動作を確認できる?

できる。claude plugin validateが、フック、API呼び出し、読み取る環境変数を一覧にしてくれる s6。