Claude Code のモッドとは何か、そして全エージェントに組み込んでいるモッド

2026年10月1日、Claude Code 2.1.287 が 1 行の changelog とともにリリースされました。「Added Claude Mods」。その 4 日後、AgentsRoom は自分が動かす Claude エージェントに、私たちのモッド（mod）の 1 つを読み込ませ始めました。

この記事では、モッドとは何か、従来の拡張ポイントにはできなかった何ができるのか、どう書き、読み込み、テストするのか、そして AgentsRoom が起動するすべての Claude エージェントにモッドを組み込んで学んだことを説明します。Claude Code に関する事実は、Claude Code 2.1.318 をインストールした状態で 2026年11月9日に読んだドキュメントと changelog に基づいています。

短く答えると。 モッドとは hooks module を持つ Claude Code のプラグインです。hooks module は JavaScript または TypeScript のファイルで、イベントが起きると Claude Code が自分のプロセスの中からその関数を呼び出します。関数はイベントを通すことも、書き換えることも、Claude Code の代わりに応答することもできます。モッドはこうしてペインを描き、コマンドを追加し、シェルコマンドを実行前に止めます。

モッドとは何か

Claude Code にはもともとプラグインがありました。.claude-plugin/plugin.json にマニフェストを持つフォルダで、スキル、サブエージェント、settings hook、MCP サーバーをまとめ、1 つの単位としてインストールできるようにするものです。モッドは、プラグインが持てるものがもう 1 つ増えたものです。プラグインの hooks/hooks.json が modules キーでコードファイルを指定すると、Claude Code はそのファイルを読み込み、エクスポートされた register 関数を呼び出します。このときそのプラグインはモッドと呼ばれます。

register の中で on(event, hook) を呼ぶたびに、関数がイベントに結び付けられます。ツールが動く前の tool.call、プロンプトを送ったときの prompt.submit、session.start、スラッシュコマンドの command.run、Claude Code が画面の一部を描くときの ui.render などです。どの hook も 3 つのものを受け取ります。

• $：モッドの API。$.ui、$.command、$.fs、$.process、$.http など、モッドが自分のコードの外でできることすべてです。
• e：プレーンなデータとしてのイベント。ツール呼び出しなら、ツール名とその引数です。
• next：イベントをほかのモッドに渡し、続いて Claude Code 本来の動作に渡して、その結果を返します。

何が起きるかは、hook が next をどう扱うかで決まります。next(e) を返せば、観察しただけです。e を書き換えたコピーで next を呼べば、イベントを書き換えたことになります。next を呼ばずに自分の結果を返せば、自分で応答したことになり、ツールは一度も動かないか、Claude Code 自身の描画は行われません。

ドキュメントはこれらの関数も hook と呼んでいます。settings.json に書く hook とは別物で、Claude Code はそちらを現在 settings hook と呼んでいます。

モッド、settings hook、スキル、MCP サーバー

この 4 つは役割が重なっており、モッドはその中で最も重いものです。用が足りる最も軽いものを選びましょう。

1 つのプラグインに 4 つすべてを入れられるので、モッドは連携するスキルや MCP サーバーと一緒に配布できます。

モッドの 3 つのファイル

my-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

plugin.json はいつものプラグインのマニフェストで、名前、バージョン、説明を持ちます。hooks.json はコードを指し示します。{ "modules": ["./register.ts"] } のように、そのファイルからの相対パスを 1 つ書きます。register.ts が hooks module です。Claude Code は .js と .ts をバンドラーもビルド手順もなしに直接読み込み、許されるベアインポートは型といくつかのヘルパーのための claude-code だけです。

私たちが組み込んでいるモッド：このファイルを変えたのは誰か

AgentsRoom は同じリポジトリで複数のコーディングエージェントを動かし、「変更」タブで、どのエージェントがどのファイルを変えたかを表示します。これによりエージェントごとの作業を個別にレビューしてコミットできます。Claude の Edit ツールと Write ツールで書かれたファイルは簡単でした。Claude Code が settings hook で知らせてくれるからです。シェルコマンドで書かれたファイルはそうはいきません。sed -i、ヒアドキュメント、codemod、rm はファイル用のツールを一切通りません。

モッド以前、私たちは推測していました。AgentsRoom はエージェントのセッションのトランスクリプトを読んで各 Bash コマンドの開始と終了の時刻を知り、ファイルの更新時刻をその時間帯と突き合わせていました。たいていはうまくいきましたが、はっきりわかる 3 つの失敗がありました。

• 削除されたファイルには更新時刻がないため、削除は誰の変更にもなりませんでした。
• grep のような読み取り専用のコマンドでも時間帯が開き、その間にエージェントが何を書いたかわかりませんでした。
• トランスクリプトの形式に依存しており、Claude Code はそれを自由に変えられます。

モッドがこの推測をなくします。私たちの agentsroom-changes モッドは、2 つのシェルツールについて tool.call を hook します。コマンドが動く直前にリポジトリのスナップショット（git status と、変更のある各パスのサイズと更新時刻）を取り、直後にもう 1 つ取ります。差のあるパスがそのコマンドで変わったもので、削除も含まれます。モッドはそれをローカルの HTTP エンドポイント経由で AgentsRoom デスクトップアプリに送ります。Claude Code 自身が読み取り専用と判定した呼び出しは、何も主張しません。

以下が短縮した hook です。ファイル全体は 177 行で、その大半はスナップショットとその上限の処理です。

import type { Register } from 'claude-code';

const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    if (!SHELL_TOOLS.has(e.tool)) return next(e);
    const ready = await prepare($).catch(() => null); // agent id, repo root, snapshot
    if (!ready) return next(e);                        // outside AgentsRoom: do nothing
    const callId = e.tool_use_id;
    post($, ready.agentId, { kind: 'start', callId });
    const ran = await next(e);                         // the command runs here
    const wroteNothing = ran.deny !== undefined || ran.isReadOnly === true;
    await reportEnd($, { ...ready, callId }, wroteNothing)
      .catch(() => post($, ready.agentId, { kind: 'end', callId, paths: [] }));
    return ran;                                        // Claude sees the normal result
  });
};

デスクトップアプリはモッドを自分のフォルダにコピーし、インストールされている Claude Code が 2.1.287 以降の場合に限り、各 Claude エージェントを claude --plugin-dir <that folder> で起動します。このモッドは 2026年10月5日、AgentsRoom 1.201.0 で提供しました。

組み込んで学んだこと

モッドがユーザーのツール呼び出しを犠牲にしてはならない。 私たちの hook は、Claude が実行するすべてのシェルコマンドの前に立っています。例外を投げたりネットワークを待ったりすれば、Claude の作業が止まります。すべての処理をガードし、デスクトップアプリへの送信はどれも送りっぱなしにし、受け入れる待ち時間は git status のスナップショット 2 回だけで、それぞれ 15 秒が上限です。送信が失われても失うのは 1 件の帰属だけで、コマンドは失いません。

求められていないときは何もしない。 モッドは、AgentsRoom が自分のエージェントに設定する環境変数を読みます。それがなければ、たとえば誰かがフォルダを自分の環境にコピーした場合、どの hook もそのまま next(e) に進みます。

--plugin-dir で読み込んだフォルダは監視される。 そのフォルダ内のファイルが変わると Claude Code はモッドを再読み込みし、再読み込みのたびに register がもう一度実行されます。これがインストール方法を決めました。デスクトップアプリは内容が変わったときだけモッドのファイルを書きます。エージェントを起動するたびに無条件で書き直すと、すでに開いているすべての Claude コンソールでモッドが再読み込みされてしまうからです。

API が変わることを前提にする。 イベントやメソッドはリリースごとに変わりうるもので、ドキュメント自身がそう書いています。--plugin-dir からモッドを読み込むと、Claude Code は実行中のバージョンの型宣言を .claude-plugin/types/ に書き出します。私たちは Web ページではなく、その型宣言に対して型チェックをしています。そして、あるビルドが私たちのモッドを読み込めなくなっても、何も壊れません。モッドが準備完了を報告しないので、AgentsRoom は以前のトランスクリプト方式に戻ります。

自分で書く

入り口は 2 つあります。

Claude に頼む。 対話型の Claude Code セッションで、欲しいモッドを説明します（「プロンプトの上に現在の git ブランチを表示して」）。Claude は組み込みのスキル plugin-authoring を使ってそのセッション用のフォルダにモッドを書き、Claude Code は Claude が書いたモッドを有効にするかを一度だけ尋ねます。はいと答えると、そのターンの終わりにモッドが読み込まれ、モッドを変更したターンのあとには毎回再読み込みされます。

3 つのファイルを自分で書き、次を実行します。

claude --plugin-dir ./my-mod       # load it for one session, hot reload on save
claude plugin validate ./my-mod    # what Claude Code reads from it, without running it
claude plugin test                 # run the mod's *.test.ts files, no session needed

claude plugin validate は、モジュールが扱うイベントを示す hooks: 行と、呼び出すモッド API のメソッドをすべて示す calls: 行を出力します。扱うつもりのイベントがそこになければ、Claude Code もその hook を呼びません。静的解析にはルールがあります。呼び出しは毎回省略せずに書く（$.ui.toast(...) とし、const ui = $.ui とはしない）、イベント名は文字列リテラルで渡す、インポートするのは相対パスで指定した自分のファイルだけ、です。

モッドを共有するときは、プラグインとして扱います。フォルダを送るか、マーケットプレイス（.claude-plugin/marketplace.json を持つリポジトリ）に載せれば、/plugin install <name>@<marketplace> でインストールしてもらえます。

今すぐ読めるモッド

• Claude Code に組み込み：/plugin の Installed タブの Built-in セクションにあります。その中には /diff ペインや、AGENTS.md をプロジェクトの指示として読むローダーがあり、Anthropic はそのソースをテストとともに anthropics/claude-code リポジトリ の mods フォルダで公開しています。同じく組み込みで、有効にするまでオフになっているのが You should know です。あなたや Claude が見落としたかもしれない点を指摘するサイドエージェントです。
• Anthropic のサンプル：claude-code-playground リポジトリにあります。プロンプトの上に描くコンテキストウィンドウの予測、危険なシェルコマンドを保留して何が変わるかを見せるガード、直前のターンの編集を順にたどる /replay コマンドです。
• 私たちのモッド：上で説明したとおり、インターフェースをまったく持たず、tool.call の hook が 1 つあるだけのモッドです。必要なのがペインではなくデータなら、真似するのに良い形です。

他人のモッドをインストールする前に

モッドはサンドボックスで隔離されていません。あなたの権限で動きます。ファイルを読み書きし、環境変数や設定（API キーを含む）を読み、プログラムを起動し、ネットワークリクエストを送り、すべてのプロンプトとツール呼び出しを見て、あなたに確認が来る前にツール呼び出しを承認できます。Claude Code のサンドボックスを有効にしていても、それが守るのは Claude が実行する Bash コマンドであり、モッドが起動するプロセスではありません。

だからインストールする前に読みましょう。モッドをクローンし、フォルダに対して claude plugin validate を実行します。hooks: 行と calls: 行を見れば、何も実行せずに、それが何を聞き取り、何に手を伸ばすかがわかります。プロンプトの上に帯を描くだけのモッドが $.http や $.process を呼ぶ理由はありません。インストールしたすべてのモッドを止めるには、1 回のセッションだけ --safe-mode で起動するか、~/.claude/settings.json で "disableAllHooks": true を設定します。

モッドが動く場所

描画するモッドは、自分がどこで動いているかを確認し、何も描画されない場所ではテキストに切り替えるべきです。

AgentsRoom では

何もインストールする必要はありません。Claude Code 2.1.287 以降では、各 Claude エージェントがモッド付きで起動し、「変更」タブには、各シェルコマンドが作成、変更、削除したファイルが、それを行ったエージェントの横に表示されます。それより古い Claude Code では、AgentsRoom はこれまでどおりトランスクリプトからシェルによる書き込みを突き合わせます。

同じ考え方は、可能なほかの CLI でも動いています。oh-my-pi には同じ取り決めの拡張機能があり、ほかの CLI はこれまでどおりの方法でシェルによる書き込みを突き合わせます。Claude Code が各ステップで公開するものをさらに活用したいなら、Claude Code の hook ガイドで、モッドと並んで動く settings hook を解説しています。

よくある質問

Claude Code のモッドとは何ですか？

モッドとは、hooks module を含む Claude Code のプラグインです。hooks module は JavaScript または TypeScript のファイルで、ツール呼び出し、プロンプトの送信、画面の一部の描画など何かが起きたとき、Claude Code が自分のプロセスの中からその関数を呼び出します。各関数はイベントをそのまま通すことも、書き換えることも、自分で処理することもできます。だからモッドはペインを描いたり、コマンドを追加したり、危険なシェルコマンドを保留したりできるのです。

モッドを使うにはどの Claude Code のバージョンが必要ですか？

ターミナルでは Claude Code 2.1.287 以降です。2026年10月1日にリリースされ、changelog には「Added Claude Mods」と書かれています。Claude Desktop アプリの Code タブは 2.1.286 から対応しています。VS Code 拡張機能では hook は動きますが、モッドが描くものを表示するには拡張機能 2.1.299 以降が必要です。確認するには claude --version を実行してください。

モッドと Claude Code の hook の違いは何ですか？

settings.json に書く hook は、イベントが発生したときに Claude Code の外でシェルコマンド、HTTP リクエスト、またはプロンプトを実行します。モッドの hook は Claude Code の中で動く関数です。settings hook にはできないことができます。インターフェースへの描画、Claude のターンなしで動くスラッシュコマンドの追加、ツール呼び出しの書き換えや、ツールを実行せずに応答すること、hook 間での状態の共有です。

Claude Code のモッドは安全にインストールできますか？

モッドはサンドボックスで隔離されていません。あなたの権限で動き、ファイルや環境変数を読み、プログラムを起動し、ネットワークリクエストを送り、ツール呼び出しを承認できます。信頼できる作者のモッドだけをインストールし、先にフォルダに対して claude plugin validate を実行してください。モッドを実行せずに、それが hook するイベントと行う呼び出しを一覧表示します。

Claude Code のモッドの例はどこで見られますか？

Anthropic は、/diff ペインや AGENTS.md ローダーなど一部の組み込みモッドのソースを anthropics/claude-code リポジトリの mods フォルダで公開し、サンプルのモッドを anthropics/claude-code-playground リポジトリで公開しています。この記事で紹介する AgentsRoom のモッドは 4 つ目のタイプの例です。インターフェースを持たず、tool.call の hook が 1 つあるだけのモッドです。

モッドを無効にできますか？

はい。/plugin の Installed タブで個別のモッドを無効にするか、--safe-mode で 1 回だけセッションを起動するか、~/.claude/settings.json で disableAllHooks を true にすれば、インストールしたすべてのモッドが settings hook とともに止まります。--safe-mode と disableAllHooks では組み込みモッドは動き続けます。それらは /plugin で 1 つずつ無効にします。