Claude Code Mod とは？仕組み・できること・安全性

Claude Code Mod とは、自分で書いた JavaScript や TypeScript を Claude Code の中で実行するプラグインのことで、Claude Code の見た目や動作を変えられます。たとえば、プロンプトの上に1行表示する、ステータスラインに数値を出す、危険なシェルコマンドを拒否する、スラッシュコマンドを追加する、といったことが可能です。Mod は Claude Code 2.1.287 で導入され、デフォルトで有効になっています。

このガイドでは、Mod が何で構成されているか、何に触れられて何に触れられないか、設定ファイルのフック・MCP サーバー・スキルとどう違うか、そしてインストールしても安全かをどう判断するかを説明します。最後に、2分で作れる実際に動く Mod も紹介します。

Claude Code Mod とは何ですか？#

Mod は、通常の Claude Code プラグインに hooks モジュール というファイルを1つ追加したものです。このモジュールは register(on, options) 関数をエクスポートします。Claude Code はプラグインを読み込むときに register を呼び出し、Mod は on(...) を使って「ツールが実行されようとしている」「ターンが完了した」「スピナーが描画されている」といったイベントを購読します。

各ハンドラーは3つの引数を受け取ります。

• $：Mod API です。Mod が及ぼす作用はすべてこれを経由します。$.ui.status、$.ui.toast、$.process.run、$.fs.read、$.command.register などがあります。
• e：イベントです。たとえば、これから実行されようとしている Bash コマンドなどです。
• next：イベントを Claude Code 本来の処理に引き渡す関数です。

ハンドラーにできることは3つあります。観察する（next(e) を呼んで結果を確認する）、書き換える（変更したイベントで next を呼ぶ）、応答する（next を呼ばずに独自の結果を返す。ガードがツール呼び出しを拒否するのはこの方法です）。

プラグインを Mod にするのは、たった1つのキーです。hooks/hooks.json に modules が含まれていれば、そのプラグインは Mod です。

{
  "modules": ["./register.js"]
}

Mod は Claude Code のプロセス内で、あなたのユーザー権限で実行されます。サンドボックス化はされていません。その代わりの利点として、あらゆる作用は $ を経由しなければならないため、Claude Code は実行前に Mod のソースを読み取り、どのイベントを処理し、どの API を呼び出すのかを正確に一覧表示できます。

Mod で何を変えられますか？#

イベントの種類は多いものの、ほとんどの Mod が使うのは一部の領域だけです。

ほかにも Mod は、ペインを開く、Claude が呼び出せるツールを登録する、サブエージェントを実行する、ファイルを読み書きする、HTTP リクエストを送る、小さなキーバリューストアにデータを保存する、といったことができます。これらはいずれも $ の呼び出しであり、検証時に表示されます。

Mod の UI は、ターミナル（JetBrains プラグインを含む）とデスクトップアプリの Code タブに描画されます。VS Code 拡張機能のチャットパネル、claude -p、Agent SDK では、フックは実行されますが何も描画されません。そのため、ガード系の Mod はヘッドレス実行でも保護を続けますが、ステータスライン系の Mod はテキストを表示する場所がないだけ、ということになります。

Mod・フック・MCP サーバー・スキルの違いは？#

この4つの拡張ポイントは、名前が似ているだけで中身は別物です。

• 設定ファイルのフック は、決まったタイミング（ツールの実行前、実行後、停止時）でシェルコマンドを実行します。別プロセスとして動き、stdin と stdout の JSON で Claude Code とやり取りします。UI の描画や、状態を保持し続けることはできません。
• Mod は型付き API を使ってプロセス内で動作します。フックにできることに加えて、描画箇所への表示、コマンドやツールの登録、そしてスピナーの描画やコンパクションの開始など、フックからは見えないイベントへの反応もできます。
• MCP サーバー は、プロトコルを通じて Claude に新しいツールやデータソースを提供します。いつ呼び出すかは Claude が判断します。Claude Code のインターフェースを変えたり、組み込みツールに割り込んだりはしません。
• スキル は、タスクに合致したときに Claude が読み込む指示やファイルです。変わるのは Claude が知っていることであり、Claude Code の動作ではありません。

おおまかな目安として、Claude に新しいことを 知ってほしい 、または できるようにしたい ならスキルか MCP サーバーを使いましょう。Claude Code 自体の 見た目 や 動作 を変えたいなら、Mod を書きましょう。

Claude Code Mod は安全ですか？#

Mod はターミナルでできることなら何でもできるため、インストールはほかの開発ツールを入れるときと同じ感覚で慎重に行ってください。次の3つの習慣でリスクを小さく抑えられます。

1. validate の出力を読む。 claude plugin validate <dir> は、モジュールごとに hooks: 行と calls: 行を表示します。ステータスライン系の Mod なのに $.http.fetch や $.fs.write が並んでいたら、もう少し詳しく確認する価値があります。
2. 権限バッジを確認する。 ClaudeMods の各 Mod ページでは、これらの呼び出しを「コマンドを実行する」「ツール呼び出しに割り込む」といったわかりやすいラベルに変換し、それぞれが必要な理由を一文で説明しています。
3. オフにする方法を知っておく。 /plugin disable <name> で特定の Mod をオフにできます。claude --safe-mode を使うと、すべての Mod を無効にした状態でセッションを開始できます。設定に "disableAllHooks": true を追加すれば、常にオフのままにできます。

組織ではさらに踏み込んだ管理ができます。管理者は、管理対象の Mod だけを許可する、--plugin-dir によるサイドロードをブロックする、承認済みのガード Mod をユーザーがインストールしたものより先に実行させる、といった設定が可能です。詳しくは Mod 管理者向けドキュメント をご覧ください。

どの Claude Code バージョンが必要ですか？#

claude --version を実行してください。ターミナルでは 2.1.287 以降 が必要です。デスクトップアプリには独自の Claude Code が同梱されており、そちらでは 2.1.286 から Mod が動作します。このサイトの各 Mod には最後に動作確認したバージョンが記載されており、執筆時点では 2.1.291 です。

小さな Mod を作って動きを見てみる#

必要なファイルは3つだけです。次の構成を作ります。

hello-status/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

.claude-plugin/plugin.json：

{
  "name": "hello-status",
  "version": "0.1.0",
  "description": "Writes a fixed message to the Claude Code status line",
  "author": { "name": "Your Name" }
}

hooks/hooks.json には、先ほど紹介した modules キーを書き、./register.js を指定します。続いて hooks/register.js です。

export function register(on) {
  on('session.start', async ($, e, next) => {
    const started = await next(e)
    $.ui.status('hello from my first mod')
    return started
  })
}

実行する前に検証しましょう。

claude plugin validate ./hello-status

Claude Code 2.1.291 では、次のように表示されます。

  ❯ ./register.js hooks: session.start
  ❯ ./register.js calls: $.ui.status

✔ Validation passed

では、今回の実行だけ Mod を読み込んでセッションを開始します。

claude --plugin-dir ./hello-status

ステータスラインにメッセージが表示されます。register.js を編集して保存すると、Claude Code は再起動なしでモジュールを再読み込みします。Mod は hello-status@inline として読み込まれ、終了すると消えます。テストや公開の方法は Mod チュートリアル で解説されています。

Mod はどこで見つかりますか？#

Mod はプラグインマーケットプレイスを通じて配布されています。マーケットプレイスとは、marketplace.json を持つ Git リポジトリまたは URL のことです。ClaudeMods も1つ運営しており、ディレクトリ に掲載している各 Mod には、デモ動画、インストールコマンド、オプション、処理を担うコード、使用する権限をまとめたページがあります。どの Mod も、ページを公開する前に実際の Claude Code ビルド上で検証・テスト・録画を行っています。

さっそく追加してみませんか？Claude Code Mod のインストール方法 では、すべてのインストール方法に加えて、更新や削除の手順も紹介しています。