建立 mod

• 要求 Claude 寫它：在 Claude Code 工作階段中描述你想要的
• 自己寫：按照教學學習 mod 程式碼的運作方式。你不需要 Node.js、bundler 或建置步驟，因為 Claude Code 直接載入 .js 和 .ts 檔案。

​

要求 Claude 寫 mod

​

在其他工作階段中使用 mod

• 在你啟動的工作階段中：在你的 shell 中，執行 claude --plugin-dir ~/mods/git-branch
• 對於其他人：將其新增到市場，以便他們可以安裝它

​

Claude 寫的 mod 無法載入的工作階段

• 沒有人在那裡批准：工作階段無法向你顯示提示，如在 claude -p 執行或 dontAsk mode 中
• 工作區不受信任：你還沒有接受目錄的信任提示
• Mod 已停止：你使用 --safe-mode 或 --bare 啟動，你設定了 disableAllHooks，或你的組織的受管設定阻止它

​

自己寫 mod

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

• plugin.json：plugin 的清單
• 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 如何運作

• Mod API，名為 $：mod 可以呼叫以到達自身外部的每個方法，在命名空間中，例如 $.ui 和 $.command
• 事件，名為 e：事件的輸入作為純資料，例如工具呼叫的名稱和引數
• 下一個處理程式，名為 next：一個函數，將事件傳遞給其他 mod，然後傳遞給 Claude Code 自己的行為，並返回結果

• 觀察：session.start hook 註冊命令，tool.call hook 計算呼叫並要求重新繪製。兩者都返回 next(e)，所以工作階段啟動，工具照常執行。
• 回答：command.run hook 返回自己的結果，永遠不呼叫 next。on 的第二個引數 { command: 'tally' } 是一個篩選器，稱為匹配器，所以 hook 只對 /tally 執行。
• 重寫：ui.render hook 呼叫 next 並複製 e，其 suffix 保留計數，所以 Claude Code 繪製其通常的微調器，你的文字在單詞後面

​

繼續處理 mod

​

使用 Claude 變更 mod

claude --plugin-dir ./first-mod

​

取得你版本的型別定義

​

檢查 Claude Code 從你的 mod 讀取的內容

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

• 完整拼寫每個 mod API 呼叫：$、命名空間，然後方法，如 $.store.get('notes')。你可以將 $ 傳遞給在同一檔案的頂層宣告的函數，對於你的名為 loadNotes 的函數，calls: 行然後讀取 $.store.get (via loadNotes)。將 $ 傳遞給方法、在 hook 內定義的函數或你從另一個檔案匯入的函數會失敗驗證。$.state 使用的 read 和 update 函數是可以採用它的匯入。不要將 $ 或其命名空間之一指派給變數、解構它或使用計算名稱索引它。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 的第二個變數或引數。驗證失敗，出現 "on" is declared again (shadowed)。
• 僅從 plugin 目錄內的檔案匯入，按相對路徑。允許的唯一裸匯入是 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

​

後續步驟

• 在介面中繪製：開啟窗格、在提示上方繪製，以及新增按鈕和文字欄位
• 對事件做出反應：hook 工具呼叫、提示和轉向
• 使用 mod API：新增命令和工具、呼叫模型，以及在計時器上執行工作
• 測試 mod：模擬 Claude Code 會回答的內容，以及測試計時器和繪製
• 對 mod 進行故障排除：mod 什麼都不做的原因，以及偵錯日誌
• 讀取內建 mod 的來源：完整的 plugin，每個都有其 hooks module 和測試