基本の形 | Mod API リファレンス

mod は、関数フックを1つのモジュールにまとめたプラグインです。モジュールは register(on, options) を export し、その中で on(event, matcher?, hook) を呼んでフックを登録します。フックはすべて ($, e, next) という引数を受け取ります。

$Claude Code 本体へのインターフェース。表示、モデル、セッション、ツール、ファイル、時計、ネットワークなど、モジュールの外部への操作はすべて $ を通じて行う。

eイベントの入力。すべての階層が凍結されたプレーンなデータで、直接書き換えると型エラーになり、実行時にも例外が発生する。

next(e)後続のプラグインと Claude Code 本来の処理を実行し、イベントの結果を返す。

モジュールは独立した実行環境で動作し、DOM と Node の API は使えません（URL、TextEncoder、AbortController、crypto.subtle などの Web API は使えます）。JSX はグローバルの h と Fragment を使ってコンパイルされます。

ファイル構成

必要なファイルは3つです。$.state を使う場合は、型定義ファイルを1つ追加します。

my-mod/
├── .claude-plugin/
│   └── plugin.json        { "name": "my-mod", "version": "0.1.0", "description": "…" }
├── hooks/
│   ├── hooks.json         { "modules": ["./register.tsx"] }
│   └── register.tsx       export const register: Register = (on, options) => { … }
└── types/
    └── index.d.ts         $.state を使う場合に追加。plugin.json に "types": "./types/index.d.ts" を書く

hooks.json の modules には、hooks.json からの相対パスを1つだけ書く。
読み込まれる拡張子は .ts .tsx .jsx .js .mjs .cjs .mts .cts である。拡張子にかかわらず ES モジュールとして扱われ、require は使えない。
プラグイン内の別ファイルは import 宣言で読み込む。import()（動的 import）を含むモジュールは読み込まれない。
型は import type { Register } from 'claude-code' で取り込む（実行時にはこの import は空になる）。
claude plugin init が生成するのはコマンドフック型の別種のプラグインなので、mod の3ファイルは手で作成する。

register と on

import type { Register } from 'claude-code'

export const register: Register = (on, options) => {
  on('tool.call', { tool: 'Bash' }, ($, e, next) => next(e))
}

名前	説明
`register(on, options)`	モジュールのエントリポイント。戻り値は使われず、Promise を返した場合は完了まで待機される。`options` には manifest の `userConfig` の値が既定値を補った状態で入る。値が変わるとモジュールが再読み込みされ、`register` がもう一度実行される。
`on(event, hook)`	フックを登録する。`event` にはイベント名、glob（`tool.*`）、否定（`!ui.render`）のいずれかを指定する。
`on(event, matcher, hook)`	`e` の一部の形を指定し、一致したときだけフックを呼び出す（マッチャー）。型の上でも `e` が絞り込まれる。
`on(...).catch(handler)`	フックが例外を投げた、制限時間を超えた、不正な形の値を返した、のいずれかのときに代わりの値を返すハンドラを設定する。1つの登録につき1回だけ設定できる（詳細）。

フックの戻り値の返し方

書き方	意味
`return next(e)`	入力をそのまま後続に渡す。処理を観察するだけのフックはこの形で書く。
`return next({ ...e, x })`	入力を書き換えて後続に渡す。後続のプラグインと Claude Code 本体は書き換え後の値を受け取る（書き換えられる範囲はイベントごとに決まっている）。
`return { … }`（`next` を呼ばない）	フック自身が結果を返し、チェーンをそこで終える。例: `tool.call` で `{ deny }`、`command.run` で `{ text }` を返す。
`const r = await next(e); …; return r`	後続の処理の結果を確認してから処理を行う、または結果を加工して返す。

undefined を返すとフックの失敗として扱われます。next を引数なしで呼ぶと reject されます。

絞り込みの条件に一致する行がありません。