创建一个 mod

• 让 Claude 编写它：在 Claude Code 会话中描述你想要的内容
• 自己编写：按照教程学习 mod 代码的工作原理。你不需要 Node.js、打包工具或构建步骤，因为 Claude Code 直接加载 .js 和 .ts 文件。

​

让 Claude 为你编写一个 mod

​

在其他会话中使用 mod

• 在你启动的会话中：在你的 shell 中，运行 claude --plugin-dir ~/mods/git-branch
• 对于其他人：将其添加到市场，以便他们可以安装它

​

Claude 编写的 mod 无法加载的会话

• 没有人在那里批准：会话无法向你显示提示，如在 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 模块

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 的第二个参数 { command: 'tally' } 是一个过滤器，称为匹配器，所以 hook 仅对 /tally 运行。
• 重写：ui.render hook 使用 e 的副本调用 next，其 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

• 完整拼写每个 mods 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)。
• 仅从插件目录内的文件导入，通过相对路径。唯一允许的裸导入是 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 工具调用、提示和转折
• 使用 mods API：添加命令和工具、调用模型、在计时器上运行工作
• 测试 mod：存根 Claude Code 会回答的内容，以及测试计时器和绘图
• 排查 mod 故障：mod 什么都不做的原因和调试日志
• 阅读内置 mod 的源代码：完整的插件，每个都有其 hooks 模块和测试