SpyBara
Go Premium

plugins/mods/reference.md 2026-10-01 23:59 UTC to 2026-10-02 10:01 UTC

This page contains 326 additions and 0 deletions.

2026
Fri 2 10:01

mod リファレンス

Claude Code の mod の完全なリファレンス：フックモジュールの構成、イベント、mods API メソッド、描画箇所、サーフェス別の要素、制限、設定。

v2.1.287 時点の Claude Code CLI と Desktop アプリについて、mod が処理できるイベント、呼び出せる mods API メソッド、描画できる描画箇所を調べられます。各項目には名前と 1 行の説明があり、解説しているガイドのセクションがある場合はそこへのリンクも記載しています。

ファイル

mod は、次のファイルを含むプラグインディレクトリです。

ファイル 必須 内容
.claude-plugin/plugin.json はい プラグインのマニフェスト。mod によって追加される必須フィールドはありません。
hooks/hooks.json はい modules：フックモジュールへのパスを 1 つ含む配列で、パスはこのファイルからの相対パスです（例："modules": ["./register.js"]）。hooks の下に設定フックを置くこともできます。
hooks/register.js などのフックモジュール はい mod のエントリポイント。register(on, options) をエクスポートします。名前は .js、.mjs、.cjs、.jsx、.ts、.mts、.cts、.tsx のいずれかで終わります。ES モジュールです。
マニフェストの types で指定する types/index.d.ts mod が $.state を使う場合、または mods API に名前空間を追加する場合 PluginState の値と、mod が追加する名前空間を宣言します
名前が .test.ts または .test.tsx で終わるファイル いいえ claude plugin test が実行するテスト

register は on と options を受け取ります。options には、マニフェストが宣言する userConfig フィールドの値が、デフォルト値を補った状態で入っています。

フック関数

mod は、イベントハンドラーである各フックを register 内で on を呼び出して登録します。on は、イベント名、省略可能な matcher（イベントのフィールドに対するフィルター）、フックを受け取ります（例：on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))）。on は、フックのエラーハンドラーを設定する .catch(handler) メソッドを 1 つだけ持つ登録オブジェクトを返します。

引数 内容
$ mods API：mods API メソッドのすべてのメソッド。各呼び出しは、名前空間、メソッドの順に省略せずに書きます（例：$.fs.read('notes.md')）。
e イベントの入力。深く凍結されたプレーンなデータです。変更するには、コピーを next に渡します。
next(e) ミドルウェアと同様の次のハンドラー。このフックの後のフックを実行し、次に Claude Code の動作を実行します。イベントの結果に解決されます。
next.signal イベントが破棄されたときに中止される AbortSignal
next.origin イベントを発火したものの { plugin, tier }。Claude Code 自身は { plugin: 'engine', tier: 'core' } です。mod の tier は、mod が実行される順序における優先度グループで、prepend、user、append、builtin のいずれかです。
next.budget フックの制限時間（ミリ秒）：next.budget.ms は制限全体、next.budget.remainingMs は現時点の残り時間です
next.to(e, tier) 後の tier（append、builtin、core のいずれか）までスキップします。next.to(e, 'append') はユーザーがインストールした mod をスキップします。呼び出せるのは prependPlugins または appendPlugins にある mod だけです。
next.error、next.called .catch ハンドラー内でのみ使用できます。next.error.kind は throw または timeout、next.error.message はエラーのテキストで、失敗したフックが next を呼び出していた場合は next.called が true になります。

イベント

イベントは対象ごとにグループ化されており、それぞれ発火するタイミングと、そのイベントのフックが返せる値を記載しています。turn.step と process.spawn のフックは非同期ジェネレーターで、それ以外のフックは非同期関数です。

各表の最後の列では略記を使っています。next(e) はイベントを変更せずに渡します。next({ ...e, text }) は、指定したフィールドを変更したコピーを渡します（例：next({ ...e, text: e.text.trim() })）。オブジェクトは next を呼び出さずにイベントに応答し、reason などの語はユーザーが書く文字列を表します（例：{ deny: 'Use the file tools.' }）。

ツール

ツールイベントは、Claude が読む説明から呼び出しを実行するかどうかの判定まで、Claude が行う各ツール呼び出しの前後で発火します。

イベント 発火するタイミング フックが返せる値
tool.call ツールが実行される直前 next(e)、{ deny: reason }、または { result }
tool.check tool.call フックと PreToolUse フックの後、Claude Code がツール呼び出しを実行してよいかを判定するとき。next(e) は、ルール、権限モード、それらのフックが下した判定に解決されます。 { decision }（allow、ask、deny のいずれか）
tool.describe 各ツールにつき 1 回、その説明が初めて Claude に送信されるとき { description }

プロンプトと Claude が読むもの

プロンプトイベントは、ユーザーが入力するテキストと、システムプロンプトやリマインダーなど Claude Code が独自に Claude へ送信するテキストを対象とします。

イベント 発火するタイミング フックが返せる値
prompt.submit プロンプトが送信されるとき next({ ...e, text })、next({ ...e, context })、または { drop: reason }
prompt.fill、prompt.suggest テキストが下書きとして、または薄い表示の候補としてプロンプトボックスに入る直前 テキストを変更した next(e)
prompt.edit ユーザーがプロンプトボックスを編集するとき next(e)
prompt.compose Claude Code がシステムプロンプトを生成するとき { sections }（送信順に並んだ { id, text, scope } のリスト）
prompt.section システムプロンプトの名前付きセクションごとに 1 回。e.name は prompt.compose におけるそのセクションの id です。 { text }、またはセクションを省くには { text: null }
prompt.context 会話ごとに 1 回、最初のメッセージとともに送信されるコンテキストについて { blocks }
prompt.attachment Claude Code がリマインダーなど独自のメッセージを Claude 向けに追加するとき。e.type は種類を示し、型で宣言されている種類については、テキストの元になった事実が e.detail に入っています。 { text }、または省くには { text: null }
skill.prompt スキルのテキストが Claude 向けに展開されるとき { text }
attribution.text Claude Code がコミットまたはプルリクエストの帰属テキストを作成するとき { text }

コマンドと設定

コマンドと設定のイベントは、コマンドが実行または一覧表示されるとき、および /config の行が表示または変更されるときに発火します。

イベント 発火するタイミング フックが返せる値
command.run コマンドが実行される直前 { text }、{}、または next(e)
command.describe 各コマンドにつき 1 回、コマンド一覧のため { description, argumentHint, isHidden }
config.set /config の行が変更される直前 next({ ...e, value }) または { deny: reason }
config.describe /config の各行につき 1 回 { label, description, isHidden }

ターン

ターンイベントは、1 つの回答を開始から終了まで、その中のモデルへの各リクエストも含めて追跡します。

イベント 発火するタイミング フックが返せる値
turn.start ターンが始まるとき next(e)
turn.step 1 つのリクエストがモデルに送信される直前 yield* next(e)、または next({ ...e, model })、next({ ...e, effort })
turn.complete ターンが終了したとき next(e)、または回答の下に 1 行表示するには { text }

セッション

セッションイベントは、セッションの開始、終了、コンパクト化、および他のセッションとのメッセージのやり取りを示します。

イベント 発火するタイミング フックが返せる値
session.start 読み込まれた mod ごとに 1 回、最初のプロンプトの前。その mod の再読み込み後にも再度発火します。/clear、/resume、/branch の後には発火しません。 next(e)
session.end セッションが終了するとき、または /clear、/resume、/branch が実行されるとき。e.reason は clear、resume、logout、prompt_input_exit、other のいずれかです。/branch は resume を報告します。 next(e)
session.compact 会話がコンパクト化される直前 { skip: reason }
session.receive、session.send 他のエージェントやセッションからメッセージが届いたとき、またはそこへ送信される直前。セッション間でメッセージを送受信するを参照してください。 receive では { consumed: reason }、send では { isDelivered: false, reason }
session.append プロンプト、応答ブロック、ツールの結果、通知など、会話が保持する各行につき 1 回、保存される前 行の content を書き換えるには next({ ...e, message })
session.attach、session.detach 別のアプリがセッションに接続または切断するとき next(e)
session.measure 各ターンの後、およびプランの制限の使用率が変化したとき next(e)

サブエージェント

サブエージェントイベントは、サブエージェントの種類が Claude に提示されるときと、サブエージェントが起動する直前に発火します。

イベント 発火するタイミング フックが返せる値
agent.offer サブエージェントの種類が Claude に提示されるとき 提示しないようにするには { isOffered: false }
agent.spawn サブエージェントが起動する直前 { model } または { deny: reason }

インターフェース

インターフェースイベントは、Claude Code が描画箇所を描画するときと、mod が描画したコントロールをユーザーが使用するときに発火します。ui.render フックが返すものについては、インターフェースに描画するを参照してください。

イベント 発火するタイミング
ui.render 描画箇所が描画される直前
ui.resolve mod が読み込まれるとき、アプリ、描画箇所、mod の組み合わせごとに 1 回。結果は、$.ui.resolve(e) が読み取る要素テーブルになります。
ui.press、ui.input、ui.select mod が描画した Button、Input、Select が使用されたとき
ui.focus、ui.scroll フォーカスされているコントロール、またはペインやバンドのスクロール位置が変わる直前
ui.close ペインが閉じる直前。e.id はそのペインで、e.origin.kind は plugin、person、unload のいずれかです。
ui.message Client 要素が自身の mod にデータを送信するとき

他の mod

これらのイベントを使うと、mod は他の mod の読み込み時にその mod を操作し、拒否したり、その mod が受け取る mods API を変更したりできます。

イベント 発火するタイミング フックが返せる値
plugin.register フックモジュールが読み込まれる直前。e.uses には、claude plugin validate が出力するのと同じ形で、そのモジュールのイベント、mods API 呼び出し、環境変数、状態が列挙されます。各呼び出しは fs.read のように $. プレフィックスなしで書かれます。 { refuse: reason }
engine.create この mod 用の mods API が構築されているとき 名前空間を追加または除外した、変更済みの mods API

テレメトリ

テレメトリイベントは、Claude Code がログに記録する使用状況レコードについて発火します。

イベント 発火するタイミング フックが返せる値
telemetry.log、telemetry.mark テレメトリレコードがログに記録される直前、または機能の 1 回の使用がマークされるとき。インストールする mod では、on('telemetry.log', { to: 'collector' }, hook) のように、テレメトリフックにフィルター { to: 'collector' } を指定してください。フィルターがないと、その mod は claude plugin validate で不合格になります。* はこれらのイベントにマッチしません。 next(e)、または { deny: reason }

設定フックのイベント

各設定フックのイベントは、classic.Stop や classic.PostToolUse のように classic.<Event> という名前のイベントです。e はフックの stdin JSON です。

mods API 呼び出し

すべての mods API メソッドは、fs.read、model.complete、ui.open のように名前空間とメソッドにちなんだ名前のイベントでもあります。これらのフックは、そのフックの後に実行される mod からの呼び出しをインターセプトし、next(e)、{ deny: reason }、または { value } を返せます。

mods API メソッド

mods API は、すべてのフックが受け取る $ 引数です。そのメソッドは $.ui などの名前空間にグループ化されています。この表では各名前空間のメソッドを名前で列挙しているため、$.ui の行の open は $.ui.open(...) の呼び出しを意味します。ガイドではよく使うものの使用例を示しており、お使いのビルド用の型ではすべてのメソッドが例とともに説明されています。

名前空間 メソッド
$.plugin name、root：このプラグインの名前とディレクトリ
$.ui resolve、invalidate、open、close、panes、focus、scroll、toast、status、log、notice、ask、copy、blit
$.command register、run、list
$.tool register、call、check、list
$.agent register、spawn、list
$.model complete、fork、classify
$.prompt submit、read、fill、suggest、compose。Claude は、submit({ text }) のテキストを、その mod を送信者として示す文の後に読みます。submit({ text, asUser: true }) は、その文なしで、テキストをユーザー自身の言葉として送信します。
$.turn abort
$.session messages、cwd、root、model、turns、id、repo、surfaces、usage、version、compact、send、append、authorize。usage() は { startedAt, context, rateLimits, cost } を返します：context には tokens、window、percent があり、rateLimits は { kind, percentUsed, resetsAt } のリストです。
$.config list、set
$.settings read
$.env get、set
$.fs read、write、list、exists、stat、ancestors。write はアトミックではありません：ファイルの内容をその場で置き換えるため、別のプロセスが書き込み途中のファイルを読む可能性があります。複数のセッションが変更するデータは $.store に保存してください。
$.store get、set、delete、keys。マシン上のすべてのセッションが共有するキーバリューストアです。複数のセッションから保存するを参照してください。
$.state リアクティブな状態：get、set。ヘルパーの atom、read、update、derive、memberOf は claude-code からインポートします
$.clock now、sleep、after、every
$.http fetch
$.process run、spawn
$.mcp call、connect。connect(server) は、自身のプラグインのマニフェストに記載されている MCP サーバーに接続します。
$.audio play、speak
$.telemetry log、mark。レコードが送信されるのは、Claude Code または組み込みの mod が呼び出した場合だけです。

描画箇所

描画箇所は、Claude Code のインターフェースにおける拡張ポイントです。各行は ui.render フックにおける e.component の値で、e.props のフィールドと、それを描画するアプリを示しています。e.surface は terminal または desktop です。各描画箇所でフックができることは、Claude Code がすでに描画しているものを変更するで、選択肢ごとの例とともに説明しています。

描画箇所 e.props e.requestId 描画されるアプリ
Pane title、isFocused、bodyColumns、placement、scroll、view ペインの id Terminal、Desktop
AbovePrompt hasSurvey、isWorking、maxRows、bodyColumns、scroll、view 1 つのインスタンス Terminal、Desktop
UserMessage text、origin、isExpanded、および origin に応じて task または from メッセージ ID Terminal、Desktop
AssistantMessage 返信のテキスト メッセージ ID Terminal、Desktop
ToolUse、ToolResult、ToolGroup ツールの名前、入力、結果 ツール呼び出し ID Terminal、Desktop
CommandOutput command、text メッセージ ID Terminal、Desktop
AskUserQuestion 質問と選択肢 ツール呼び出し ID Terminal、Desktop
ToolProgress kind ツール呼び出し ID Terminal
Spinner word、message、suffix、mode エージェント ID Terminal、Desktop
TurnDuration word、durationMs メッセージ ID Terminal
InfoNotice text、command メッセージ ID Terminal
SessionMode modes 1 つのインスタンス Terminal、Desktop
PromptHint isDraft、isWorking、hint 1 つのインスタンス Terminal、Desktop

e.viewport には columns、rows、isFullscreen が入っています。アプリがウィンドウを計測するまでは存在しません。その rows はウィンドウ全体の高さであり、ペインの高さではありません。

ツリーを描画箇所に合わせるには、フック内で次の props を読み取ります。

  • Pane またはバンドの幅：e.props.bodyColumns に合わせて描画します
  • トランスクリプトの横にある Pane の高さ：e.props.placement が 'dock' の場合、e.props.scroll.bodyRows がペインの行数です
  • プロンプトの上にある Pane の高さ：e.props.placement が 'inline' の場合、ペインはツリーに合わせて上限まで大きくなり、bodyRows は現在表示されている行だけを数えます。$.ui.open の rows フィールドで別の上限を指定できます。

ペインより高いツリーは、全体としてスクロールします。

要素

要素は ui.render フックが返すツリーの構成要素で、$.ui.resolve(e) から取得します。要素からツリーを構築するではよく使う要素をターミナルでの描画例とともに紹介しており、インターフェースギャラリーにはほとんどの要素のスクリーンショットがあります。チェックマークは、そのアプリが要素を描画できることを示します。

要素 主な props Terminal Desktop
Box key、flex レイアウト、gap、padding、margin、width、height、borderStyle、backgroundColor、position、hover ✓ ✓
Text color、backgroundColor、bold、italic、underline、dimColor、inverse、wrap ✓ ✓
Button key、label、onPress、hotkey、plain、dimColor、autoFocus、action ✓ ✓
Link href、label ✓ ✓
Code コード（最大 10,000 文字） ✓ ✓
Markdown text（最大 10,000 文字）、key、dimColor、onLinkPress、pressableLinks ✓ ✓
Input key、label、placeholder、value、submitLabel、onSubmit、onInput、autoFocus ✓ ✓
Select key、label、options、value、onSelect、autoFocus ✓ ✓
Svg SVG ドキュメント（最大 131,072 文字） ✓
Client module、key ✓ ✓
Raster key、columns（最大 512）、rows（最大 256）、cells。色付きセルのグリッドを描画するを参照してください。 ✓
Image 最大 2 MiB の PNG または RGBA バイト、またはファイルパス ✓

Button のその他のルール：action は Claude Code 独自のキーボードショートカットのアクションの 1 つを指定し、そのアクションに対するユーザーの割り当てがコードまたは修飾キー付きのキーである場合、その割り当てでボタンが押されます。バンド内のボタンに数字の hotkey を指定すると、ユーザーが空のプロンプトにその数字だけを入力して手を止めたときにも発火します。1 つの描画内で 2 つのボタンが同じ hotkey を指定した場合は、後のボタンが優先されます。autoFocus はどのコントロールでも true しか受け付けないため、オフにするには props を省略してください。

制限

フックと mods API 呼び出しは、時間とサイズの制限の下で実行されます。Claude Code は、時間制限を超えたフックをスキップし、サイズ制限を超えた呼び出しを拒否します。

制限 値
1 つのイベントに対するフック自体の実行時間（next 内や、$.clock.sleep 以外の mods API 呼び出し内の時間は含まない） 10 秒
.catch ハンドラーの実行時間 1 秒
すべての session.end フックの合計 1.5 秒
$.process.run のタイムアウト デフォルトは 30 秒、最大 10 分
$.model.complete の maxTokens デフォルトは 1024、最大 64,000 またはモデルの出力上限
$.fs.read と $.fs.write 1 ファイルあたり 4 MiB
Text の 1 つの文字列の子 10,000 文字
$.store JSON の合計で 4 MiB
$.session.messages() 最新の 4,096 エントリ
$.ui.invalidate('ui.render') による再描画 1 秒あたり 10 回に制限。ターミナルでは、表示中のペイン、展開されたバンド、プロンプト下のヒント行については 30 回。それより早い呼び出しはまとめられます。
$.ui.toast { timeoutMs } を渡さない限り 4 秒間表示
ユーザーが求めずに開かれたペイン ターミナルの幅が 144 列以上で配置。ユーザーが一度開いた後は 110 列以上
コマンド、ツール、サブエージェントの種類、ペインの名前 英字、数字、_、-、最大 64 文字
1 つの claude plugin test テスト テストが timeoutMs を設定しない限り 5 秒

設定と環境変数

mod に影響する設定と環境変数は次のとおりです。「場所」列には、それぞれがどの設定ファイルまたは環境から読み取られるかを示しています。

名前 場所 動作
CLAUDE_CODE_PLUGIN_DIRS 環境、または ~/.claude/settings.json の env フラグを渡せないアプリ向けに、--plugin-dir と同様に読み込むプラグインディレクトリ。:（Windows では ;）で区切った絶対パスです。
CLAUDE_CODE_PLUGIN_DIR_WATCH 環境 1 にすると、長時間実行される非対話型セッションが、保存時に --plugin-dir の mod を再読み込みします
prependPlugins、appendPlugins 管理設定。管理設定のないマシンで、Team または Enterprise プランでサインインしていないユーザーの場合に限り、ユーザー設定。 acme-guard@acme-tools などのプラグイン ID のリスト。prependPlugins の mod はユーザーがインストールしたすべての mod の前に、appendPlugins の mod は後に、記載された順序で実行されます。mod が実行される順序を参照してください。
allowManagedModsOnly 管理設定（組み込みガードのオプションとして） 組織のものとみなされる mod と、Claude Code に組み込まれた mod だけが読み込まれます。ユーザーの設定フックは引き続き実行されます。
allowModsToOverrideDenyRules 管理設定（組み込みガードのオプションとして） ユーザーがインストールした mod が、deny ルールで拒否されるツール呼び出しを承認できるようにします
allowManagedHooksOnly 管理設定 組織のものではないフックとインストール済みの mod をブロックします。引き続き実行されるものを参照してください。
disableAllHooks 任意の設定ファイル 管理設定では、インストール済みプラグインの mod やフックは一切実行されません。ユーザー自身の設定では、組織が管理するものは引き続き実行されます。disableAllHooks を参照してください。
disableSideloadFlags 管理設定 起動時に --plugin-dir と --plugin-url を拒否します
pluginConfigs ユーザー設定または管理設定 mod の userConfig 値を保持します。キーは acme-guard@acme-tools などのプラグイン ID で、--plugin-dir で読み込んだ mod の場合は first-mod@inline のように名前と @inline です

sec-default@builtin は Claude Code に組み込まれたガードで、/plugin とデバッグログには cc-plugin-sec-default として表示されます。管理設定のあるマシン、または Team か Enterprise プランでサインインしたユーザーの場合、ユーザーがインストールするすべての mod より先に読み込まれます。管理設定の prependPlugins が設定されている場合、このガードはそのリストに記載されているときにだけ、記載された位置で読み込まれます。ソースは Claude Code リポジトリの mods/sec-default ディレクトリにあります。

コマンド

以下のコマンドとフラグで、mod の読み込み、検査、テストを行います。claude コマンドはシェルで、/ コマンドは Claude Code のプロンプトで実行します。表中の <directory> は、claude plugin validate ./first-mod のように入力するパスを表します。角括弧は省略可能な引数を示します。

コマンド 動作
/plugin 組み込みではない mod が読み込まれている場合、タブの下に 1 mod active · first-mod のような行を表示します
claude plugin validate <directory> プラグインのマニフェストとフックモジュールを読み取り、エラー、処理するイベント、行う mods API 呼び出しを報告します。--strict は警告をエラーとして扱い、--json は機械可読なレポートを出力します。
claude plugin test [directory] ディレクトリ（指定しない場合はカレントディレクトリ）の下にある、名前が .test.ts または .test.tsx で終わるすべてのファイルを実行します。テストが失敗するとステータス 1 で終了します。
claude --plugin-dir <directory> 1 つのセッションでプラグインディレクトリを読み込み、保存時にそのフックモジュールを再読み込みします。複数読み込むにはフラグを繰り返し指定します。
/reload-plugins 実行時にプラグインを再読み込みします