Mod を作る・試す

Mod（モッド、mod）は、エントリファイル（フックモジュール）を持つ Claude Code のプラグインです。フックモジュールは JavaScript か TypeScript のファイルで、イベントが起きると Claude Code がその中の関数を呼びます。Node.js もバンドラーもビルドも要りません（.js と .ts をそのまま読み込みます）。何ができるか、設定のフック・スキル・MCP サーバーとの比べ方は Mod（モッド）を使う（Mod が合うか迷うなら先に読みます）、画面に描く方法は Mod で画面に描く、ファイルの形や API の一覧は Mod のリファレンスにあります。

作り方は2通りです。

• Claude に書かせる：Claude Code のセッションで欲しいものを説明する
• 自分で書く：チュートリアルで Mod のコードの動き方を学ぶ

Claude に Mod を書かせる#

対話セッションで欲しい Mod を説明すると、Claude が書きます。Claude は組み込みのスキル plugin-authoring に従います。このスキルは、書き込み先・使っている版にあるイベントとメソッド・Mod の読み込まれ方を Claude に教えます。Mod を頼むと Claude が読み込むほか、/plugin-authoring で自分で読み込むこともできます。

Mod が動くのは、あなたが承認したあとです（承認できないセッションは後述）。

1. Mod を説明する：たとえば make a mod that shows the current git branch above the prompt のように頼みます。Claude は、そのセッション用の Mod フォルダ（~/.claude/dev-mods/ の下にセッション ID のフォルダ）の中に、Mod ごとのディレクトリを作って書きます。例：~/.claude/dev-mods/3f2a9c1e-5b7d-4e8a-9c21-6d0f4b8a7e13/git-branch/
2. Mod を承認する：Claude が最初のファイルを保存すると、このセッションでホットリロードを有効にするかを聞かれます。
   • 「Enable for this session」：セッションの Mod フォルダにある Mod が、ターンの終わりに読み込まれ、変更のあったターンの終わりごとに読み直される。答えはセッションを再開しても続く
   • 「Not now」：今は何も読み込まれない。ファイルは残り、そのセッションを次に始めたときに読み込まれる。読み込ませたくないなら、そのディレクトリを削除する
3. 読み込まれたか確かめる：/plugin を開き、Tab で「Installed」タブへ進みます。Mod が並び、ここでオフにもできます。
4. 試す：頼んだ機能を使います。思ったとおりでなければ Claude に直してほしい点を伝えます。ファイルが変わったターンの終わりに読み直されるので、Claude が終えたらすぐ試せます。

ほかのセッションで使う#

Claude が書いた Mod は、それを作ったセッションでだけ読み込まれます。そのセッションの Mod フォルダは、cleanupPeriodDays より古くなると削除されます。残すには、Mod のディレクトリを自分の場所（例：~/mods/git-branch）へコピーし、読み込み方を選びます。

• 自分が始めるセッション：claude --plugin-dir ~/mods/git-branch
• ほかの人向け：マーケットプレイスに入れて、インストールしてもらう（「Mod を配る」を参照）

Claude が書いた Mod が読み込まれないセッション#

Claude が書いた Mod は、承認したうえで、Mod の実行が許されている信頼済みのワークスペースでだけ読み込まれます。次のセッションでは読み込まれません。

• 承認する人がいない：確認を出せないセッション（claude -p の実行や dontAsk モード）
• ワークスペースが信頼されていない：そのディレクトリの信頼の確認に答えていない
• Mod が無効：--safe-mode か --bare で起動した、disableAllHooks を設定した、または組織の管理設定が止めている

自分で Mod を書く#

ここでは first-mod を作ります。Claude のツール呼び出しを数えて作業中のスピナーの横に出し、回数を表示する /tally コマンドを足す Mod です。書き終えたら、Claude Code が書き出す型定義と claude plugin validate で、使っている版のイベントとメソッド、Claude Code がコードから読み取る内容を確かめます。

ファイルは3つです。

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

• plugin.json：プラグインのマニフェスト
• hooks.json：コードのファイルを指す
• register.js：自分のコード（フックモジュール）

1. ディレクトリを作る#

mkdir -p first-mod/.claude-plugin first-mod/hooks

PowerShell の場合：

New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks

2. マニフェストを書く#

Mod もプラグインなのでマニフェストが要りますが、Mod 用の特別なフィールドはありません。first-mod/.claude-plugin/plugin.json に保存します。

{
  "name": "first-mod",
  "version": "0.1.0",
  "description": "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command",
  "author": { "name": "Your Name" }
}

3. コードの場所を教える#

プラグインを Mod にするのは、hooks/hooks.json の modules キーです。値には hooks.json からの相対パスでコードのファイルを書きます。first-mod/hooks/hooks.json に保存します。

{
  "description": "The first-mod hooks module",
  "modules": ["./register.js"]
}

4. コードを書く#

Mod が読み込まれると、Claude Code はこのファイルが export する register を呼び、on 関数を渡します。on を1回呼ぶごとに、指したイベントのハンドラー（フック）が1つ登録されます。first-mod/hooks/register.js に保存します。

// 下のフックが共有する回数
let calls = 0

// Mod が読み込まれたときに1回呼ばれる
export function register(on) {
  // セッションの開始時（最初のプロンプトの前）
  on('session.start', async ($, e, next) => {
    await $.command.register({
      name: 'tally',
      description: 'Show how many tool calls Claude has made',
    })
    return next(e)
  })

  // Claude がツールを使う直前
  on('tool.call', async ($, e, next) => {
    calls += 1
    // 新しい回数が出るよう描き直しを頼む
    $.ui.invalidate('ui.render')
    return next(e)
  })

  // /tally を打ったときだけ（第2引数のマッチャーで絞る）
  on('command.run', { command: 'tally' }, async () => {
    return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }
  })

  // スピナーを描くたび。本体のスピナーの言葉のあとに回数を足す
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

5. 読み込んで試す#

--plugin-dir を付けると、インストールせずに1セッションだけディレクトリを読み込めます。

claude --plugin-dir ./first-mod

ツールを何回か使う頼みごと（例：list the files here and read the README）をすると、スピナーが Thinking · tool calls: 2… のようになります。終わってから /tally を実行すると、first-mod: Claude has made 2 tool calls since this mod loaded のように出ます（先頭のプラグイン名は Claude Code が付けます）。

コマンドだけなら非対話モードでも確かめられます。

claude -p "/tally" --plugin-dir ./first-mod

first-mod: Claude has made 0 tool calls since this mod loaded

/tally がコマンドの一覧に無ければ、モジュールが読み込まれていません。下の「Mod が何もしない原因を探す」を見ます。

6. セッション中にコードを変える#

セッションを開いたまま、ui.render フックの ' · tool calls: ' を ' · tools used: ' に変えて保存します。

  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · tools used: ' + calls + '…' } })
  })

トランスクリプトに first-mod を読み直したこととフックの一覧が出て、次のスピナーから Thinking · tools used: 1… になります。

この例の仕組み#

どのフックも、同じ3つの引数を受け取ります。

first-mod のフックは、イベントの扱い方の3つの型をそれぞれ使っています。

• 見るだけ：session.start（コマンドを登録）と tool.call（数えて描き直しを頼む）。どちらも next(e) を返すので、セッションの開始もツールの実行もいつもどおり進む
• 答える：command.run は自分で結果を返し、next を呼ばない。第2引数 { command: 'tally' } はマッチャーで、/tally のときだけ動く
• 書き換える：ui.render は suffix を入れた e のコピーを next に渡す。本体がいつものスピナーを描き、言葉の後ろに自分の文字が付く

--plugin-dir で読み込んだディレクトリは、ファイルが変わるとホットリロードされます。そのたびに register が走り直すので、calls は 0 に戻ります。読み直しをまたいで値を残す方法は、Mod で画面に描くの「状態を保つ」にあります。

Mod を育てる#

Mod が読み込まれたら、Claude に直させる、使っている版の型定義でコードを検査する、Claude Code がコードから読み取るイベントと呼び出しを一覧する、テストする、ができます。

Claude に Mod を直させる#

すでにある Mod を変えるときは、その Mod のディレクトリを --plugin-dir で指してセッションを始めます。Claude が書いたものが同じセッションで読み込まれます。

claude --plugin-dir ./first-mod

そのうえで、たとえば add a /tally-reset command to this mod that sets the tally back to zero と頼みます。Claude はフックモジュールを編集し、claude plugin validate を実行して、出た問題を直します。--plugin-dir で読み込んだディレクトリは保護されたパスなので、default と acceptEdits のモードでは Claude の編集ごとに承認を求められます（ほかの権限モードでの扱いは、権限モードのページの保護されたパスの表）。Claude がターン中に保存したファイルは、ターンの終わりに読み直されるので、終わったらすぐ /tally-reset を試せます。

使っている版の型定義を得る#

--plugin-dir に渡したディレクトリの Mod、または Claude が書いた Mod を Claude Code が読み込む（読み直す）たびに、Mod のディレクトリの .claude-plugin/types/ に TypeScript の型定義ファイル（.d.ts）が書き出されます。いま動かしている Claude Code の版にあるイベント・mods API のメソッド・要素が正確に書かれているので、エディターで補完と型検査ができます。次のファイルが置かれます。

Mod に自前の tsconfig.json が無いと、生成されたものを継承する tsconfig.json が Mod のルートに足されます。そのため、エディターと tsc -p ./first-mod が追加設定なしで型を検査します。

イベントとメソッドは版ごとに変わりえます。このページを含め、どのページとも食い違ったら、この生成ファイルを信じます。claude-code/index.d.ts は、mods API の全メソッドにコメントと例が付いた、その版でいちばん詳しい資料です。名前（例：'tool.call'）でファイルを検索して調べます。Claude Code のリポジトリの mods/types/claude-code.d.ts でもオンラインで読めます（1行目に書いた版の名前が入っています）。

Claude Code が読み取る内容を確かめる#

コードを実行せず、セッションも始めずに、Claude Code から見た Mod を確かめるには claude plugin validate を使います。マニフェストを検査し、Mod の読み込み時と同じ静的解析をフックモジュールのソースに対して行います。Mod のディレクトリに対して実行します。

claude plugin validate ./first-mod

first-mod では、出力に次の行が含まれます。

  ❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}
  ❯ ./register.js calls: $.command.register, $.ui.invalidate

✔ Validation passed

hooks: の行は、モジュールがフックするイベントを、絞り込みを波括弧に入れて並べます。calls: の行は、呼ぶ mods API のメソッドをすべて並べます。環境変数を読み書きするモジュールには env reads: と env writes: の行が、$.state を使うモジュールには state reads: と state writes: の行も付きます。

扱うつもりのイベントが1行目に無ければ、Claude Code もそのフックを呼びません。よくある原因はイベント名の綴りの間違いで、"tool.calls" is not an event のようなエラーで報告されます。

静的解析がすべてのフックと呼び出しを見つけられるよう、次の決まりを守ります。

• mods API の呼び出しは完全な形で書く：$、ネームスペース、メソッドの順（$.store.get('notes')）。$ は、同じファイルのトップレベルで宣言した関数には渡せる（自作の loadNotes なら calls: の行が $.store.get (via loadNotes) になる）。メソッド・フックの中で定義した関数・ほかの自分のファイルから import した関数へ $ を渡すと検査に失敗する。$.state が使う read と update の関数だけは、import していても渡せる。$ やそのネームスペースを変数に代入する・分割代入する・計算した名前で引くこともしない（const ui = $.ui は $.ui is used as a value で失敗する）
• on の呼び出しのイベント名は、文字列リテラル（'tool.call' など）で書く。変数や名前の一覧のループは the event name passed to on() is not a string literal で失敗する
• register の中に、on という名前の変数や引数をもう1つ宣言しない。"on" is declared again (shadowed) で失敗する
• import してよいのはプラグインのディレクトリの中のファイルだけで、相対パスで書く。bare import（パスでない名前の import）で許されるのは、型といくつかの補助関数のための claude-code だけ
• import 宣言はファイルの先頭に書く（import { name } from './file.js'）。動的な import() は a dynamic import(); a hooks module imports its own files with an import declaration で失敗する
• どのファイルも ES モジュールで書き、require でなく import を使う。読み込まれる拡張子はリファレンスにある

Mod をテストする#

claude plugin test は、Mod の自動テストをシェルから実行します。セッション・サインイン・ネットワークは要りません。テストがイベントを発火させ、フックがしたことを確かめるので、問題をセッションに持ち込む前に見つけられます。

テストファイルの決まりは次のとおりです。

• テストキット（claude-code/testing モジュール）を import する
• 名前は .test.ts で終える。置き場所はプラグインのディレクトリのどこでもよい（例：first-mod.test.ts）
• test() を最低1つ書く。無いと declares no test(): nothing ran で失敗する
• Mod 自身のファイルや隣の .ts の補助ファイルも import できる。ゲームのルールのような普通の関数は、キットなしで単体テストできる

次のテストは、ツール呼び出しを2回発火させてから /tally を実行し、答えが2回を数えているかを見ます。first-mod/tests/first-mod.test.ts に保存します。

import { expect, test } from 'claude-code/testing'

test('/tally reports the tool calls the mod has seen', async ($, on) => {
  // Claude Code の代わりにツール呼び出しへ答える。ツールは実行されない
  on('tool.call', () => ({ result: 'ok' }))

  // 2回発火させる。Mod の tool.call フックが数える
  await $.tool.call({ tool: 'Bash', command: 'ls' })
  await $.tool.call({ tool: 'Read', file_path: 'README.md' })

  // /tally を実行し、フックが返したテキストを確かめる
  const answer = await $.command.run({ command: 'tally', args: '' })
  expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')
})

first-mod ディレクトリで実行します。

claude plugin test

tests/first-mod.test.ts:
(pass) /tally reports the tool calls the mod has seen [22.87ms]

 1 pass
 0 fail
Ran 1 test across 1 file. [0.19s]

$.tool.call は Mod の tool.call フックを通ってから（回数が増えてから）スタブへ渡るので、ls は実行されず、ファイルも読まれません。$.command.run の answer は、Mod の command.run フックが返したオブジェクトです。

失敗したテストがあると終了ステータス 1 で終わるので、CI に組み込めます。実行するシェルで Mod を読み込めないときも、claude plugin test: hooks modules are turned off で始まる行と理由を出して、終了ステータス 1 で終わります。

Claude Code の答えをスタブにする#

テストの中ではモデル・ストア・ツールが動かないので、Mod が Claude Code の答えを待つところはテストがスタブで答えます。テスト関数が受け取る2つの引数を使います。

次はモデルの呼び出しをスタブにする例です。grader という Mod の /grade コマンドは、文を1つモデルへ送り、返事が PASS で始まるかを報告します（ファイルにはテスト対象のフックだけを載せています。実際の Mod には plugin.json・hooks.json と、セッションで打つためのコマンドの登録も要ります）。

export function register(on) {
  on('command.run', { command: 'grade' }, async ($, e) => {
    // e.args は /grade のあとに打った文字
    const reply = await $.model.complete({
      model: 'haiku',
      system: 'Grade the sentence. Start your reply with PASS or FAIL.',
      prompt: e.args,
    })
    const passed = reply.isAnswered && reply.text.startsWith('PASS')
    return { text: passed ? 'Passed' : 'Try again' }
  })
}

import { expect, test } from 'claude-code/testing'

test('a passing grade is reported', async ($, on) => {
  // $.model.complete に決まった返事で答える。モデルは動かない
  on('model.complete', () => ({
    value: {
      isAnswered: true,
      text: 'PASS\nNice sentence.',
      usage: { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
    },
  }))

  const answer = await $.command.run({ command: 'grade', args: 'The cat sat on the mat.' })
  expect(answer.text).toBe('Passed')
})

フックの reply は value の中身で、text が PASS で始まるのでテストは通ります。もう一方の枝は、text が FAIL で始まるスタブで2つ目のテストを書き、Try again を期待します。

スタブが返す形は2通りです。

• mods API の呼び出しのスタブ：value フィールドを持つオブジェクト。value が Mod の中でその呼び出しが解決する値になる（{ value: 7 } なら $.store.get が 7）
• Claude Code のイベントのスタブ（turn.step・tool.call など）：そのイベント自身の結果（{ result: 'ok' } など）。$.session.send と $.prompt.fill も、下の表のとおりイベントの結果の形で返す

スタブの誤りや不足は、失敗したテストの出力の the engine reported: の見出しの下に出ます。

• returned neither { value } nor { deny }：mods API の呼び出しのスタブが、値をそのまま返した
• no implementation for と名前：Mod がその呼び出しをしたが、答えるスタブが無い

ネームスペースごと答えるメモリ内のモックもあります。

• mock.clock(on)：$.clock に答える。テストが進める模擬の時計を返すので、タイマーのテストが待たずに済む
• mock.store(on, { count: 7 })：その中身で始まるストアで $.store に答える。戻り値は無いので、Mod が保存した値を確かめるなら、store のスタブ2つを自分で書く（下の描画のテストと同じ）
• mock.env(on, { CI: 'true' })：その環境変数で $.env.get に答える

テストキットの決まり#

書き始めてすぐ出るエラーは、たいてい次のどれかです。

• スタブは、テストが $ を最初に呼ぶ前にすべて登録する：あとで on を呼ぶと、on("ui.render") after the test first called $ のようなエラーになる

• session.start は自動では走らない：各テストは、モジュールを読み込み直した状態（フックは1つも呼ばれておらず、モジュールレベルの変数は初期値）で始まる。session.start で用意するものに頼るフックなら、先に発火させる

  typescriptコピー

  // フックが next(e) で渡したあとのイベントに答える
  on('session.start', () => ({ cwd: '/work' }))
  // フックが呼ぶ $.command.register に答える
  on('command.register', () => ({ value: undefined }))
  await $.session.start({ surface: 'terminal', isInteractive: true, cwd: '/work' })
  

  2つ目のスタブが無いと、チュートリアルのような session.start フックの $.command.register が no implementation for command.register で拒否され、キットがフックを飛ばすので、その後ろは実行されません。その時点ではテストは失敗せず、あとの検査が失敗したときにだけ、飛ばされたフックが the engine reported: の下に並びます。

• next(e) を返すフックには、答えるスタブが要る：たとえば Claude の待機中は何も描かないよう ui.render フックが next(e) を返すと、マウントが no implementation for ui.render で失敗する。要素をそのままのデータで返すスタブを登録すると、マウントは通り、フックが next(e) を返したときは ui.find({ type: 'Text' }) がその要素を返す

  typescriptコピー

  // その場所に Claude Code が描くものの代わり
  on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))
  

• turn.step のスタブは非同期ジェネレーター：テストは、結果を得るためにストリームを最後まで読む

  typescriptコピー

  on('turn.step', async function* ($, e) {
    // yield 1つが、ストリームで届く返事の1片
    yield { kind: 'text', index: 0, text: 'ok' }
    // return がリクエスト全体の結果
    return { turnId: e.turnId, index: e.index, answer: 'ok', toolUses: [], stopReason: 'end_turn', usage: null }
  })
  
  const stream = $.turn.step({ turnId: 't', index: 0, model: 'claude-test', messageCount: 1 })
  let step = await stream.next()
  while (step.done !== true) step = await stream.next()
  const result = step.value
  

  読み終えた result は、Mod の turn.step フックが手を加えたあとの、スタブが返したオブジェクトです（ここでは result.answer が 'ok'）。

• ツール呼び出しは、ツール名と引数をフィールドにして発火する：await $.tool.call({ tool: 'Bash', command: 'ls' })。{ result } を返す tool.call のスタブも登録する

スタブが返すものの一覧#

Mod がテストの中でする mods API の呼び出しには、すべてスタブが要ります。例外は、キットが自分で答える $.ui.invalidate と $.state の呼び出しです。$.clock には mock.clock(on) を使います（無いと $.clock.now() が no implementation for clock.now で失敗します）。

表の1列目は Mod がする呼び出し（または next(e) で渡すイベント）、2列目はその名前で on に渡す関数です（$.store.get の行なら on('store.get', ($, e) => ({ value: saved.get(e.key) }))）。'...' は自分で埋めます。

expect には toBe・toEqual・toMatch・toMatchObject・toContain・toBeDefined・toBeUndefined・toThrow があり、どれにも前に .not を付けられます。

タイマーをテストする#

const clock = mock.clock(on) は、0 から始まり、テストが動かしたときだけ進む模擬の時計を返します。待たずに時間を進められるので、タイマーで動く Mod のテストに使います。別の時刻から始めるときはミリ秒で渡します（mock.clock(on, { now: 5000 })）。

例は countdown という Mod の /countdown コマンドです。受け取った秒数から1秒ごとの $.clock.every で数え下げ、0 になるとトーストを出します（grader と同じく、テスト対象のフックだけを載せています）。

export function register(on) {
  on('command.run', { command: 'countdown' }, async ($, e) => {
    let left = Number(e.args)
    const timer = $.clock.every(1000, () => {
      left -= 1
      if (left === 0) {
        timer.cancel()
        $.ui.toast('Time is up')
      }
    })
    return {}
  })
}

import { expect, mock, test } from 'claude-code/testing'

test('the countdown ends with a toast', async ($, on) => {
  const clock = mock.clock(on)
  // Mod が出したトーストの文を集める
  const toasts: string[] = []
  on('ui.toast', ($, e) => {
    toasts.push(e.text)
    return { value: undefined }
  })

  await $.command.run({ command: 'countdown', args: '3' })
  // 2秒たってもまだ出ない
  await clock.advance(2000)
  expect(toasts).toEqual([])
  // 3秒目で 0 になって出る
  await clock.advance(1000)
  expect(toasts).toEqual(['Time is up'])
})

advance は期限が来たタイマーが走り終わってから解決するので、次の行の検査にはその結果が反映されています。トーストが早く出ないことと、1回だけ出ることを確かめられます。

描画をテストする#

$.ui.mount は、Mod の ui.render フックを通して描画先を1つ描き、描いた要素を押す・入力する・探すためのハンドルを返します。surface で描く先のアプリを選べるので、1つのテストで複数のアプリを試せます。次は Mod で画面に描くの「タブ付きのペインを作る」のペインを、ターミナルとデスクトップアプリで1回ずつ描き、タブを切り替えてボタンを押します。

import { expect, test } from 'claude-code/testing'

// このペインの ui.render フックに Claude Code が渡すもの（アプリを除く）
const PANE = {
  plugin: 'hello-tabs',
  component: 'Pane',
  requestId: 'hello-tabs',
  viewport: { columns: 100, rows: 30 },
  props: {
    title: 'Hello tabs',
    isFocused: true,
    bodyColumns: 60,
    placement: 'inline',
    scroll: { offset: 0, bodyRows: 10 },
    view: {},
  },
} as const

test('the second tab counts presses and saves the count', async ($, on) => {
  // $.store を Map で置き換え、保存された値を読めるようにする
  const saved = new Map<string, unknown>()
  on('store.get', ($, e) => ({ value: saved.get(e.key) }))
  on('store.set', ($, e) => {
    saved.set(e.key, e.value)
    return { value: undefined }
  })

  for (const surface of ['terminal', 'desktop'] as const) {
    const ui = await $.ui.mount({ ...PANE, surface })
    // Mod が付けた key でボタンを押す
    await ui.press({ key: 'tab-two' })
    await ui.press({ key: 'more' })
    expect(await ui.find({ type: 'Text', text: /^Count: \d+$/ })).toBeDefined()
    await ui.unmount()
  }

  // 2つのアプリで1回ずつ押したので 2
  expect(saved.get('count')).toBe(2)
})

hello-tabs ディレクトリで claude plugin test を実行すると、両方のアプリが回数の行を描き、Mod が 2 を保存していれば通ります。2回のマウントは同じ読み込み済みのモジュールを使うので、回数は次のアプリへ引き継がれます。

ハンドルのメソッドは次のとおりで、要素は付けた key で指します。

どのメソッドもハンドラーが終わってから解決するので、次の行で結果を確かめられます。props には、その描画先で Claude Code が渡すものを入れます（描画先ごとの props はリファレンスの描画先の表に、型は使っている版の型定義にあります）。

描画のテストで分かるのは、フックが返した木と、それがそのアプリで有効かどうかまでです。アプリが実際にどう描くかは分からないので、新しいレイアウトは実際のセッションでも見ます。

/clear のあとの描画をテストする#

各テストは、すべての $.state が既定値の状態、つまり /clear の直後と同じ状態で始まります。/clear のあとの動きを試すには、session.start を発火させずに source: 'clear' で classic.SessionStart を発火させ、描かれるものを見ます。

次のテストは、Mod で画面に描くの「/clear のあとに保存した値を読み直す」のモジュールを確かめるもので、上の描画のテストのファイル（PANE を定義している）に足します。

test('the saved count comes back after /clear', async ($, on) => {
  // ストアにはすでに 7 が入っている
  on('store.get', () => ({ value: 7 }))
  // フックが next(e) で渡したあとのイベントに答える
  on('classic.SessionStart', () => ({}))

  // /clear のあとに起きるイベントを発火させる
  await $.classic.SessionStart({ source: 'clear' })

  const ui = await $.ui.mount({ ...PANE, surface: 'terminal' })
  await ui.press({ key: 'tab-two' })
  // 既定の 0 ではなく、保存した数が出る
  expect(await ui.find({ type: 'Text', text: 'Count: 7' })).toBeDefined()
})

classic.SessionStart のフックが、ペインを描く前に 7 を $.state へ写していれば通ります。そのフックが無いと、ペインは Count: 0 を描き、find が undefined を返して toBeDefined で失敗します。

ポリシーの Mod をテストする#

組織が prependPlugins に並べた Mod は、ほかの Mod を読み込む前に拒否できます。こうした Mod を試すには、自分の Mod の層（tier）を決め、許す・拒む相手になる2つ目の Mod をテストに渡します。

• tier：テストファイルの先頭で1回呼ぶ（tier('prepend')）。自分の Mod を prepend・append・builtin のどれかで読み込み、動く順での位置を決める。呼ばなければ user
• plugins：test の本体の前にオプションのオブジェクトを渡し、その plugins の配列に、その場で書いた Mod（name と register 関数を持つ）を並べる。user 以外で読み込むなら tier を足す

次は、Mod（モッド）を使うの管理者向けの節にあるポリシーの Mod（acme-guard）が、プロセスを起動する Mod を拒むことを確かめます。

import { expect, test, tier } from 'claude-code/testing'

// テストする Mod を、ほかのどの Mod よりも先に読み込む
tier('prepend')

// ポリシーが禁じる $.process.run を呼ぶ2つ目の Mod
const runner = {
  name: 'runner',
  register(on) {
    on('tool.call', async ($, e, next) => {
      await $.process.run(['ls'])
      return { result: 'runner answered' }
    })
  },
}

test('refuses a mod that starts a process', { plugins: [runner] }, async ($, on) => {
  on('tool.call', () => ({ result: 'claude code answered' }))
  let message = ''
  try {
    // $ を最初に呼んだときに Mod が読み込まれるので、拒否はここで投げられる
    await $.tool.call({ tool: 'Bash', command: 'ls' })
  } catch (error) {
    message = error.message
  }
  expect(message).toBe('runner: refused by acme-guard: Acme policy: mods may not call process.run')
})

キットは、テストが $ を最初に呼んだときにすべての Mod を読み込みます。自分の Mod が1つを拒むと、その呼び出しが例外を投げ、メッセージに拒まれた Mod・拒んだ Mod・理由が並びます。

逆に、禁じられたものを何も呼ばない Mod（tool.call で { result: 'reader answered' } を返すだけの reader）を plugins: [reader] で渡すと、何も拒まれず、$.tool.call の答えは reader からの { result: 'reader answered' } になります。reader がスタブより先に答えたことで、読み込まれたと分かります。

acme-guard ディレクトリで claude plugin test を実行すると、両方のテストが通ります。

Mod を配る#

Mod はプラグインなので、マニフェストで版を付け、/plugin のコマンドでインストール・更新してもらいます。配り方は相手で変わります。

• 数人：プラグインのディレクトリか、その .zip を送る（プラグインを作って配るの、マーケットプレイスなしで共有する方法）
• チーム：自分のマーケットプレイス（プラグインごとにディレクトリを持つ非公開リポジトリなど）に載せる。リポジトリで作業する全員に追加するには、リポジトリの設定にそのマーケットプレイスを登録する
• 組織全体：管理者が、管理設定で組織の Mod をインストールする（Mod（モッド）を使う）
• 誰でも：マーケットプレイスのリポジトリを公開するか、Anthropic のディレクトリへプラグインを提出する

配る前に、プラグインの name を確かめます。claude- で始まるなど、Anthropic 自身のものに見える名前は claude plugin validate が失敗にします。イベントとメソッドは版ごとに変わりえるので、どの Claude Code の版で確かめたかは README に書きます。

開発は、インストールしたコピーではなく、--plugin-dir で作業ディレクトリに対して続けます。Claude Code は、インストールしたプラグインを版ごとにキャッシュするので、版を上げて入れ直すまで、編集がインストール済みのコピーに届きません。

Mod が何もしない原因を探す#

モジュールやフックが失敗しても、Claude Code はそれを飛ばしてセッションを続けます。そのため、壊れた Mod は「何もしない Mod」に見えます。まず次の2つで手がかりを集め、そのあと下の症状から当てはまるものを探します。

• Claude Code の読み取り内容：claude plugin validate ./first-mod のように Mod のディレクトリを指して実行する。イベント名の綴りの間違い・マニフェストの不備・読めないモジュールが、セッションなしで分かる
• Claude Code が書く1行：モジュールが読み込まれない・フックが飛ばされる・ほかの Mod に拒否されると、Mod の名前を含む1行が書かれる。読む場所はセッションの種類で変わる

Mod を読み込める環境か確かめる#

Mod を持たないディレクトリでシェルから claude plugin test を実行すると、インストールもセッションもなしに、自分の設定で Mod が読み込めるかが分かります。

組織が自分たちの Mod だけを許す allowManagedModsOnly を設定していても、このコマンドには出ません。その場合、自分で入れた Mod は読み込まれず、下の「組み込みのガードのメッセージ」の行が出ます。

Mod が読み込まれない#

コマンドも描画も動作の変化も、Mod が足すものが何も出ないときです。

拒否のメッセージ#

デバッグログで、hooks module・Mod の名前・not loaded: の後ろに続く理由です。

組み込みのガードのメッセージ#

管理設定のあるマシン、または Team か Enterprise プランでサインインしたユーザーでは、組み込みのガードが、Mod やその答えを拒否することがあります。どのメッセージにも、そのルールを変えるために組織の管理者が設定するオプションの名前が出ます。

フックが飛ばされる、Mod が外される#

読み込まれたあとで、Claude Code がフックの1つを飛ばしたか、Mod を外したときです。

ツール呼び出しが拒否される#

Mod は読み込まれてフックも動いているのに、Mod が触ったツール呼び出しが拒否されるときです。

• a hook changed this call's input after the model wrote it：自動モードで拒否された呼び出しに付く理由です。サーバー側の分類器が審査したあとにフックが入力を変えたので、審査が実際に動くものを見ていません。変えたのは Mod の tool.call か turn.step、または PreToolUse の設定フックのどれかですが、メッセージはどれかを言いません。メッセージは Claude に、記録どおりにもう一度呼ぶよう伝えます。それも拒否されるなら、フックが毎回入力を変えているので、その Mod かフックをオフにするか、自動モードをやめて自分で承認します
• 設定の deny ルールについてのメッセージ：tried to lift a deny rule in your settings と the deny rules in your settings could not be checked for this call, so it is refused は組み込みのガードから出ます。上の「組み込みのガードのメッセージ」を見ます

描画が出ない・反応しない#

Mod は読み込まれたのに、ペイン・帯・部品が思ったとおりに動かないときです。

編集や値が失われる#

Mod は動いているのに、加えた変更や、Mod が持っていた値が無いときです。

デバッグログを読む#

デバッグログには、読み込んだ・拒否したすべてのモジュール、失敗したすべてのフック、拒否したすべての結果の行が残ります。トランスクリプトに何も出ないときはここを見ます。--debug か、出力先を選べる --debug-file <path> を付けて始め、別のターミナルで Mod の名前で絞って追いかけます。

claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
# 別のターミナルで
tail -f ./mod-debug.log | grep first-mod

読み込まれた Mod には、名前と扱うイベントを並べた行が出ます。--plugin-dir で読み込んだ Mod は、名前の後ろに @inline が付きます。

hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

検査に通らなかった描画も、拒否された結果として行になります。自分の行をログに書くには $.ui.log('message', { to: 'debug' }) のように第2引数を付けます（付けないと、トランスクリプトに薄い色の行が足されます）。

--plugin-dir の Mod を編集しているあいだは、読み直しのたびに Mod の名前とフックの一覧の行がトランスクリプトに出ます。保存でモジュールが壊れたときは reload failed, the previous version stays loaded: と理由の行が出て、最後に動いた版が動き続けます。

次に読むページ#

• Mod で画面に描く：ペインを開く、プロンプトの上に描く、ボタンや入力欄を足す
• Mod のリファレンス：ファイルの形・イベント・API のメソッド・描ける場所・要素の一覧
• Mod（モッド）を使う：入れ方・信頼・オンオフ・組織での管理・最初から入っている mod
• プラグインを作って配る：マニフェスト・マーケットプレイス・公開