SpyBara
Go Premium

plugins/mods/overview.md 2026-10-21 23:02 UTC to 2026-10-22 22:58 UTC

This page contains 45 additions and 45 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Tue 6 23:59 Thu 8 22:58 Wed 14 22:58 Thu 15 23:58 Mon 19 23:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59

Mods の概要

mod を使用して Claude Code にペイン、コマンド、ツール呼び出しルールを追加します。mod でできることや、mod の作成方法、インストール方法、mod が実行される場所を確認してください。

mod は Claude Code の外観と動作を変更する プラグイン です。JavaScript または TypeScript のイベントハンドラで構成されています。Claude Code はイベント（ツール呼び出し、送信されたプロンプト、インターフェイスの一部が描画されるなど）が発生したときにハンドラを呼び出し、ハンドラはイベントを監視したり、変更したり、引き継いだりできます。mod を使用して、各リクエスト後のコンテキストの満杯度をチャートするペインなど、Claude Code に独自の機能を追加します。mod のファイルと完全な例については、mod の仕組み を参照してください。

[!NOTE]

Claude Code の既存の hooks もイベントで実行されます。設定ファイルで構成するシェルコマンド、HTTP リクエスト、またはプロンプトとして実行されます。mod のハンドラは Claude Code 内で実行される関数です。Claude Code は両方の種類の hooks を呼び出します。このページでは、「hook」は mod のハンドラを意味し、設定ファイルの種類は「settings hook」です。

mod でできること

Settings hooks、skills、status lines、MCP サーバーは Claude Code の外で動作します。各々はスクリプトを実行するか、Claude にテキストまたはツールを提供します。mod は Claude Code 内で実行されるため、それらができないことができます。

  • 使用できるインターフェイスを描画する: トランスクリプトの横のペイン、またはプロンプトの上のバンド。タブ、ボタン、テキストフィールドを含みます。インターフェイスに描画する を参照してください。
  • Claude Code 独自のインターフェイスを再描画する: ツール呼び出しの行、スピナー、Claude が質問をするダイアログなど、Claude Code が自身で描画する部分を置き換えたり、スタイルを変更したりします。Claude Code が既に描画しているものを変更する を参照してください。
  • ツール呼び出しまたはリクエストに介入する: たとえば、ツール呼び出しを保持しながらユーザーに質問したり、ツールを実行せずに回答したり、1 つのリクエストを別のモデルに送信したりします。ツール呼び出しをガードまたは変更する と ターンをフォローする を参照してください。
  • コマンドで独自のコードを実行する: Claude ターンなしで、Claude が作業中でも、すぐに関数を実行する /command。コマンドまたはツールを追加する を参照してください。
  • hooks 間でデータを共有する: mod の hooks はそのファイル内の変数を共有するため、1 つの hook が記録したものを別の hook が表示できます。たとえば、1 つの hook がツール呼び出しをカウントしながら別の hook がスピナーの横にカウントを表示したり、1 つが各リクエストのトークン使用量を読み取りながら別がペインでチャートしたりできます。イベントに反応する を参照してください。

mod は Claude Code CLI、Claude Desktop アプリの Code タブ、VS Code 拡張機能で動作します。claude -p やクラウドセッションなど、他の場所での動作については、mod が実行される場所 を参照してください。設定フック、スキル、または MCP サーバーが既に必要なことを実行している場合は、mod を作成する前に それらを比較してください。組織の mod を管理するには、組織の mod を管理する を参照してください。

mod を取得する

mod を使い始めるには、次のいずれかを行います。

mod をインストールまたは更新する

[!WARNING]

Mod はユーザーの権限で実行されるコードです。ファイルの読み取りと書き込み、プロセスの開始、ネットワークリクエストの実行ができます。信頼できる著者とマーケットプレイスからのみ mod をインストールしてください。mod を信頼するかどうかを決定する を参照してください。

Mod はマーケットプレイスからプラグインとしてインストールされます。プラグインの名前、@、マーケットプレイスの名前を指定します。これらの例は、your-org という名前のマーケットプレイスから token-chart という名前のプラグインをインストールします。

  • Claude Code セッションで /plugin install token-chart@your-org を実行します。
  • シェルで claude plugin install token-chart@your-org を実行します。

プラグインをインストールする はマーケットプレイス、スコープ、VS Code 拡張機能と Desktop アプリ、および プラグインを更新し続ける をカバーしており、すべてが mod を含むプラグインに変更なしで適用されます。

セッションが開いている間にシェルから mod をインストールまたは更新する場合は、そのセッションで /reload-plugins を実行してロードします。それ以外の場合は、Claude Code を次回起動するときにロードされます。

サンプル mod を試す

Anthropic は claude-code-playground リポジトリの claude-code/mods ディレクトリ でサンプル mod を公開しています。それぞれが完全なプラグインであり、その README に作成方法が記載されています。リポジトリではこれらを現状のまま、サポートなしで公開しています。

  • token-weather: プロンプトの上にコンテキストウィンドウの予報を描画します
  • blast-radius: rm -rf や強制プッシュなどの危険なシェルコマンドを保留し、それによって何が変更されるかを、続行またはキャンセルするためのボタンとともに表示します
  • replay-theater: 直前のターンで Claude が行ったファイル編集を順に確認できる /replay コマンドを追加します

サンプル mod はユーザーの権限で実行されます。ロードする前にその動作を確認するには、フックと呼び出しを一覧表示します。

試すには、リポジトリをクローンし、--plugin-dir を使用して mod のディレクトリを 1 つのセッションでロードします。mod がロードされたことを確認するには、セッションがロードした mod を確認します。

継続して使用するには、クローンの claude-code/mods ディレクトリをマーケットプレイスとして追加し、claude-code-playground-mods から mod をインストールします。マーケットプレイスはクローンを参照しているため、クローンを移動または削除すると mod はロードされなくなります。

mod を信頼するかどうかを判断する

mod は Claude Code 内でユーザーの権限で実行されるコードです。mod は信頼できる作成者とマーケットプレイスからのみインストールしてください。

mod が到達できる範囲

mod はユーザーの権限で実行されるため、インストールする前に、それが何にアクセスできるかを知っておいてください。読み込まれると、mod は以下のことができます。

  • ユーザーのマシンでユーザーとして動作する: ユーザーアカウントがアクセスできる場所ならどこでもファイルを読み書きし、プログラムを起動し、ネットワークリクエストを行う
  • ユーザーのシークレットを読む: 環境変数と設定ファイル（どちらかに保存している API キーを含む）
  • ユーザーのセッションを見る: 送信するすべてのプロンプトと Claude が行うすべてのツール呼び出し
  • ユーザーのセッションを変更する: プロンプトまたはツール呼び出しを書き直し、ユーザーが入力したかのようにプロンプトを送信し、ユーザーの別のセッションにメッセージを送信する
  • ユーザーに尋ねずに動作する: ユーザーが尋ねられる前にツール呼び出しを承認する
  • ユーザーの使用量を消費する: ユーザーのプランまたは API キーでモデルを呼び出す

mod はサンドボックス化されません。サンドボックス化をオンにすると、サンドボックスは Claude が実行する Bash コマンドを分離しますが、mod が起動したプロセスはその外側で実行されます。

管理設定がある場合、または Team もしくは Enterprise の /login がセッションの認証情報である場合、デフォルトでは mod の承認によって呼び出しがユーザーの ask ルールや PreToolUse フックを通過することはありません。どちらもない場合、mod は ask ルールがプロンプトを表示する呼び出しや、ユーザーの PreToolUse フックがブロックした呼び出しを承認できます。deny ルールが拒否する呼び出しも mod が承認できるのはどのような場合かを確認するには、フックで権限を拡張するを参照してください。

mod は Claude Code のインターフェイスの大部分を再スタイル化できますが、権限プロンプトはできません。プロンプトが表示する内容を変更することはできません。

mod をインストールする前に、mod が何をするかをリストアップする

mod をインストールする前に、mod を実行することなく、どのイベントを処理するか、そしてファイルの読み取りやネットワークリクエストなど Claude Code に何を要求するかをリストアップできます。まず、プラグインのファイルを取得します。たとえば、リポジトリをクローンします。次に、シェルで、プラグインのディレクトリに対して claude plugin validate を実行します。

claude plugin validate ./some-mod

出力の hooks: と calls: の行は、mod が処理するイベントと Claude Code に要求する内容をリストアップします。mod が何をできるかを確認するには、出力と確認すべき呼び出しが表示されます。

mod をオンまたはオフにする

mod はデフォルトでオンです。ターミナルでは、Claude Code v2.1.287 以降を使用してください。Desktop アプリには独自の Claude Code が含まれており、mod は v2.1.286 から動作します。mod を使用する場所でバージョンを確認してください。

  • ターミナル: シェルで claude --version を実行します。古い場合は、Claude Code を更新してください。
  • Desktop アプリ: Code タブのローカルセッションで /status を入力し、Claude Code の行を確認します。2.1.286 のようなバージョンが表示されます。古い場合は、Desktop アプリを更新してください。

Mod をオフにするには、停止する数と期間を選択します。それらをオンに戻すには、同じ変更を元に戻します。

  • 1 つの mod: /plugin の Installed タブ からそのプラグインを無効化またはアンインストールする
  • すべてのインストール済み mod、1 つのセッション: --safe-mode で Claude Code を開始します。これは他のカスタマイズも無効にします。
  • インストールしたすべての mod、すべてのセッション: ~/.claude/settings.json で "disableAllHooks": true を設定します。設定のフックとカスタムステータスラインも停止します。組織が管理するものは実行し続けます。

組織を通じて Claude Code を使用する場合、管理者は、どの mod がロードされるかを制限することもできます。管理者は ユーザーがインストールした mod がロードされるのを停止する から開始します。

disableAllHooks と組織の allowManagedModsOnly は mod を停止しますが、そのプラグインの残りの部分はそのまま残します。プラグインはインストールされたままで、そのスキル、コマンド、エージェント、MCP サーバーはロードされます。その他の設定やフラグはより広範囲に影響します。disableAllHooks と allowManagedHooksOnly で実行されるもの に、それぞれがプラグインとその設定のフックに対して何を行うかが記載されています。

自分の環境で mod をロードできるかどうかを確認するには、mod がロードできるかどうかを確認する を参照してください。

[!NOTE]

早期アクセス中に CLAUDE_CODE_ENABLE_FUNCTION_HOOKS を設定した場合は、削除してください。Claude Code v2.1.287 以降はそれを無視するため、0 に設定しても mod をオフに保ちません。

セッションがロードした mod を確認する

ターミナルセッションがロードした mod を確認するには、Claude Code プロンプトで /plugin を実行します。タブの下の薄い行はカウントと名前を示します。たとえば 1 mod active · first-mod。インストールした mod がそこに名前が付いていない場合は、mod が何もしない理由を確認する を参照してください。

mod の仕組み

Mod は プラグイン であり、フックと呼ばれるイベントハンドラを登録するコードを持っています。Claude Code はイベント（Claude がツールを呼び出すときやスピナーが描画されるときなど）が発生したときにフックを実行します。小さな mod には 3 つのファイルがあります。

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

これは完全な register.js です。Claude が実行するツール呼び出しをカウントし、Claude が作業している間、Thinking · tool calls: 3… のようにスピナーの横にカウントを表示します。

// The count, shared by the two hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Ask Claude Code to draw the interface again, so the new count shows
    $.ui.invalidate('ui.render')
    // Let the tool run as usual
    return next(e)
  })

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

ファイルは 2 つのフックを登録し、両方とも上部の calls 変数を使用します。

  • tool.call フックは Claude がツールを使用しようとするたびに実行されます。calls に 1 を加え、Claude Code にインターフェイスを再度描画するよう要求し、ツールを通常どおり実行させます。
  • ui.render フックは Claude Code がスピナーを描画するたびに実行されます。Claude Code 独自のスピナーを保持し、単語の後にカウントを追加します。

この録画は mod が動作しているところを示しています。プロンプトボックスの上のスピナー行を見てください。Claude がディレクトリを一覧表示して 2 つのファイルを読む間、表示が Thinking · tool calls: 1…、次に 2…、次に 3… と変わります。