mod を作成する

• Claude に書かせる: Claude Code セッションで何をしたいかを説明します
• 自分で書く: チュートリアルに従ってmod のコードがどのように機能するかを学びます。Node.js、バンドラー、またはビルドステップは必要ありません。Claude Code は .js ファイルと .ts ファイルを直接読み込むためです。

​

Claude に mod を書かせる

​

他のセッションで mod を使用する

• 開始するセッションで: シェルで claude --plugin-dir ~/mods/git-branch を実行します
• 他の人向け: マーケットプレイスに追加して、インストールできるようにします

​

mod Claude が書いたものがロードできないセッション

• 誰も承認する人がいない: claude -p 実行や dontAsk モードのように、セッションはプロンプトを表示できません
• ワークスペースが信頼されていない: ディレクトリの信頼プロンプトを受け入れていません
• Mod が停止している: --safe-mode または --bare で開始した、disableAllHooks を設定した、または組織の管理設定がそれをブロックしている

​

自分で mod を書く

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

• plugin.json: プラグインのマニフェスト
• hooks.json: コードファイルを指します
• register.js: コード。hooks module と呼ばれます

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

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

{
  "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" }
}

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

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

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs when the session starts, before your first prompt
  on('session.start', async ($, e, next) => {
    // Add the /tally command
    await $.command.register({
      name: 'tally',
      description: 'Show how many tool calls Claude has made',
    })
    // Let the session start as usual
    return next(e)
  })

  // 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 when you type /tally, and only then, because of the matcher
  on('command.run', { command: 'tally' }, async () => {
    // The text to print in the transcript
    return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }
  })

  // 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 + '…' } })
  })
}

claude --plugin-dir ./first-mod

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

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

  // 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: ' · tools used: ' + calls + '…' } })
  })

​

例の mod がどのように機能するか

• mods API。$ という名前です。mod が自身の外に到達するために呼び出すことができるすべてのメソッド。$.ui や $.command などの名前空間内です
• イベント。e という名前です。ツール呼び出しの名前と引数などのイベントの入力。プレーンデータとして
• 次のハンドラー。next という名前です。イベントを他の mod に渡し、次に Claude Code 独自の動作に渡す関数。結果を返します

• 観察: session.start hook はコマンドを登録し、tool.call hook はコールをカウントして再描画を要求します。どちらも next(e) を返すため、セッションが開始され、ツールが通常どおり実行されます。
• 回答: command.run hook は独自の結果を返し、next を呼び出しません。on への 2 番目の引数 { command: 'tally' } はフィルターで、matcher と呼ばれます。hook は /tally に対してのみ実行されます。
• 書き直す: ui.render hook は e のコピーで next を呼び出します。その suffix はカウントを保持します。Claude Code は通常のスピナーを描画し、単語の後にテキストを描画します

​

mod の作業を続ける

​

Claude で mod を変更する

claude --plugin-dir ./first-mod

​

バージョンの型定義を取得する

​

Claude Code がモジュールから読み取るものを確認する

claude plugin validate ./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

• 各 mods API 呼び出しを完全に綴ります。$、名前空間、メソッド。$.store.get('notes') のように。$ を同じファイルの最上位で宣言された関数に渡すことができます。loadNotes という名前の関数の場合、calls: 行は $.store.get (via loadNotes) を読みます。$ をメソッド、hook 内で定義された関数、または別のファイルからインポートした関数に渡すと、検証が失敗します。$.state が使用する read および update 関数は、それを取ることができるインポートです。$ またはその名前空間の 1 つを変数に割り当てたり、分割したり、計算された名前でインデックスを付けたりしないでください。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 という名前の 2 番目の変数またはパラメーターを宣言しないでください。検証は "on" is declared again (shadowed) で失敗します。
• プラグインディレクトリ内のファイルからのみインポートします。相対パスで。許可される唯一の裸のインポートは、型といくつかのヘルパーの claude-code です。
• ファイルの最上部で import 宣言を使用します。import { name } from './file.js' のように。動的な import() は a dynamic import(); a hooks module imports its own files with an import declaration で失敗します。
• すべてのファイルを ES モジュールとして書きます。import を使用し、require は使用しません。リファレンスは Claude Code がロードするファイル拡張子をリストします。

​

mod をテストする

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

test('/tally reports the tool calls the mod has seen', async ($, on) => {
  // Answer each tool call in Claude Code's place, so no tool runs
  on('tool.call', () => ({ result: 'ok' }))

  // Raise two tool calls, which the mod's tool.call hook counts
  await $.tool.call({ tool: 'Bash', command: 'ls' })
  await $.tool.call({ tool: 'Read', file_path: 'README.md' })

  // Run /tally and check the text its hook returns
  const answer = await $.command.run({ command: 'tally', args: '' })
  expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')
})

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]

​

mod を共有する

​

次のステップ

• インターフェイスに描画する: ペインを開き、プロンプトの上に描画し、ボタンとテキストフィールドを追加します
• イベントに反応する: ツール呼び出し、プロンプト、ターンをフック化します
• mods API を使用する: コマンドとツールを追加し、モデルを呼び出し、タイマーで作業を実行します
• mod をテストする: Claude Code が答えるものをスタブ化し、タイマーと描画をテストします
• mod をトラブルシューティングする: mod が何もしない理由とデバッグログ
• 組み込み mod のソースを読む: 完全なプラグイン。各 hooks module とテスト付き