はみだしブログ

Claude Code の「mods」を入れる前に知っておきたいこと

Claude Code に「mods」という仕組みが入った。短い TypeScript（または JavaScript）の関数で、Claude Code の動きや画面を自分好みに変えられる。便利そうな話だが、公式の説明を読むと、入れる前に知っておきたい注意がかなり多い。この記事では、何ができるのかと、どこに気をつければいいのかを順に整理する。

mods とは何か

Claude Code は、ツールを呼ぶ、許可を求める、画面の一部を描く、といった動きのたびに「イベント」を出している。mod は、このイベントに割り込む関数だ。イベントの前・後・代わりに動けるので、次のようなことができる。

  • モデルに届く前にプロンプトを書き換える
  • ツールの呼び出しを止める、書き換える、やり直させる
  • 許可の問い合わせに、自分の代わりに答える
  • ツールの結果から秘密の文字列を消してから Claude に渡す

画面も変えられる。会話の横にペイン（小さな表示欄）を出したり、ボタンや入力欄を足したり、スピナーの横に数字を出したりできる。/command を足して、Claude の応答を待たずに自分の関数を動かすこともできる。

これまでも Claude Code には「フック」があった。設定ファイルにシェルのコマンドなどを書いておき、決まったタイミングで動かす仕組みだ。ただ、フックは外から動くので、イベントを書き換えたり画面を描いたりはできなかった。mods は Claude Code の中で動くので、そこまで手が届く。公式は、フックでは足りなかった要望に応えるために作った、と説明している。

始め方

mods は plugin（Claude Code の拡張の入れ物）の中に入れて配る。入れ方はふつうの plugin と同じで、CLI なら /plugin から入れられる。ターミナルでは v2.1.287 以降、デスクトップアプリでは v2.1.286 以降が要る。

自分で書かなくてもよい。Claude Code に「こういう mod がほしい」と頼めば、コードを書き、入れて、その場で読み込み直してくれる。Node.js やビルドの手順は要らず、.ts のファイルをそのまま読み込む。

おもしろいのは、Claude Code の機能の一部がすでに mod として作り直されていることだ。たとえば /diff は mod になっていて、止めたり自分の版に差し替えたりできる。公式は、今後もっと多くの機能を mod に移し、小さな芯に必要なものだけを足して使えるようにしたい、としている。

入れる前に見ておきたいこと

ここからが本題だ。公式の文書は、mods の危うさをかなりはっきり書いている。

mods は隔離されていない。 mod は Claude Code と同じ権限で、自分のパソコンの上で動く。ファイルの読み書き、プログラムの起動、ネットへの通信ができる。環境変数や設定ファイルにある API キーも読める。送ったプロンプトや Claude のツールの呼び出しもすべて見える。Bash の隔離（sandbox）を有効にしていても、それが守るのは Claude が動かすコマンドで、mod が始めた処理はその外で動く。

許可を勝手に出せる。 mod は、本来なら確認を求められるツールの呼び出しを、聞かれる前に通してしまえる。会社の管理設定やチームのプランでログインしている場合は既定で歯止めがかかるが、個人で使っている場合はその歯止めがない。

だから、信頼できる作者のものだけを入れる。 公式もこの一点を何度も繰り返している。入れる前に中身を確かめる手段も用意されていて、plugin のフォルダに対して claude plugin validate を動かすと、その mod がどのイベントに割り込み、何をしようとしているか（ファイルを読む、通信する、など）の一覧が出る。動かさずに確かめられるので、他人の mod を入れる前に一度見ておくとよい。

ひとつ安心できる点もある。mod は画面の多くを描き換えられるが、許可を求める画面だけは変えられない。何の許可を求められているかが、mod にごまかされることはない。

止め方と、チームでの扱い

困ったときの止め方は3段階ある。

  • 1つだけ止める: /plugin の Installed から、その plugin を無効にするか消す
  • その回だけ全部止める: --safe-mode を付けて起動する（ほかの自分の設定も止まる）
  • いつも全部止める: ~/.claude/settings.json に "disableAllHooks": true を書く

チームや会社のプランでは、sec-default（security default）という組み込みの mod が最初に読み込まれ、利用者が入れた mod が禁止の設定を上書きするような危ないことを止める。中身は公開されている。管理者は、自分たちの mod を先に読み込ませて、本番の設定に触るコマンドの前に確認を挟む、すべての呼び出しを記録する、といった使い方もできる。

10月上旬に出た v2.1.295 では、設定ファイル側のフックにも onFailure: "block" が足された。フックが起動できない、時間切れになる、思わぬ終わり方をした、というときに、素通りさせずに止める設定だ。mods とは別の機能だが、「割り込みの仕組みが壊れたときに安全側に倒す」という同じ流れの改善として覚えておくとよい。

まとめ

mods は、Claude Code を自分の使い方に合わせて組み替えられる強い仕組みだ。そのぶん、入れた mod は自分と同じ権限で何でもできる。他人の mod は claude plugin validate で中を見てから入れる、困ったら --safe-mode で止める、の2つだけは先に覚えておきたい。

便利さと怖さが同じ場所にある機能なので、まずは自分で頼んで作った小さな mod から試すのがよさそうだ。

出典