Anthropic发布Claude Code Mod开发指南
Getting started with Claude Code mods
Agent开发者必看，这篇把Claude Code的Hook机制讲透了，直接上手写Mod能极大扩展工具链能力。
Build your first Claude Code mod from an empty folder, then see what else the API can do.
从一个空文件夹开始构建你的第一个 Claude Code mod，然后看看 API 还能做什么。
- Author: Addy Osmani (Member of Technical Staff) - Published: 2026-10-01 - URL: <https://claude.dev/blog/getting-started-with-claude-code-mods/>
- 作者：Addy Osmani（技术员工成员） - 发布日期：2026-10-01 - URL: <https://claude.dev/blog/getting-started-with-claude-code-mods/>
Claude Code already lets you change a lot about how it behaves: settings, permission rules, slash commands, skills and a status line. Mods go further. Mods can rewrite or replace what Claude Code does, and can even draw custom UI. Under the hood, mods are hooks, and they ship inside plugins. Each one is a small JavaScript or TypeScript module that runs inside your session and sees every event as it happens.
Claude Code 已经允许你更改其行为方式的许多方面：设置、权限规则、斜杠命令、技能和状态栏。Mod 更进一步。Mod 可以重写或替换 Claude Code 的功能，甚至可以绘制自定义 UI。在底层，mod 是钩子（hooks），它们作为插件的一部分分发。每个 mod 都是一个小型的 JavaScript 或 TypeScript 模块，在你的会话中运行，并实时捕获每一个事件。
That makes mods a way to fit Claude Code to how you work. You can add a readout you check all the time, put a guard in front of the commands that make you nervous, or build a review view for how you like to read changes.
这使得 mod 成为将 Claude Code 适配到你工作方式的一种手段。你可以添加一个你随时查看的读数，为那些让你感到紧张的命令设置前置守卫，或者为你喜欢的阅读变更的方式构建一个审查视图。
This guide builds one mod from an empty folder, Token Weather, a live forecast of the context window drawn above the prompt. It's about 80 lines. Then it tours two larger mods, Blast Radius and Replay Theater, to show what else the API can do.
本指南将从一个空文件夹构建一个名为 Token Weather 的 mod，它是一个显示在提示符上方的上下文窗口实时预报。它大约只有 80 行代码。随后，我们将浏览两个更大的 mod——Blast Radius 和 Replay Theater，以展示 API 还能实现的其他功能。
Video (Terminal): Token Weather, Blast Radius and Replay Theater, one after another, in a terminal session — Title cards between three demos in a dark terminal: Token Weather's band climbing from Clear at 18% to Storm at 81%, Blast Radius holding rm -rf build with the 9 files it would delete, and Replay Theater stepping through a rename of greet to welcome.
视频（终端）：Token Weather、Blast Radius 和 Replay Theater，在一个终端会话中依次演示 — 三个演示之间在深色终端中的标题卡：Token Weather 的状态条从 18% 的晴朗（Clear）上升到 81% 的风暴（Storm），Blast Radius 展示了 rm -rf build 命令将删除的 9 个文件，以及 Replay Theater 逐步演示将 greet 重命名为 welcome 的过程。
Video (Desktop): Token Weather, Blast Radius and Replay Theater, one after another, in Claude Code on desktop — Title cards between the same three demos in the light Code tab of the Claude desktop app: Token Weather's band climbing from Clear at 10% to Storm at 77%, a Blast Radius card listing the 9 files rm -rf build would delete, and Replay Theater stepping through a rename of greet to welcome.
视频（桌面端）：Token Weather、Blast Radius 和 Replay Theater，在桌面版 Claude Code 中依次演示 — 三个演示之间在 Claude 桌面应用浅色代码标签页中的标题卡：Token Weather 的状态条从 10% 的晴朗（Clear）上升到 77% 的风暴（Storm），一张 Blast Radius 卡片列出了 rm -rf build 命令将删除的 9 个文件，以及 Replay Theater 逐步演示将 greet 重命名为 welcome 的过程。
Video: Token Weather's band as the context window fills: Clear at 18%, Showers at 67%, Storm at 81% — A one-line terminal band cycling through three forecasts, a yellow sun for Clear, a blue umbrella for Showers and a pink lightning bolt for Storm, each with its token count out of 200k and a small bar chart of recent turns.
视频：随着上下文窗口填满，Token Weather 的状态条变化：18% 的晴朗（Clear）、67% 的小雨（Showers）、81% 的风暴（Storm） — 一行终端状态条循环显示三种预报，黄色太阳代表晴朗，蓝色雨伞代表小雨，粉色闪电代表风暴，每种状态都显示基于 200k token 总数的计数以及近期轮次的小型柱状图。
Claude Code 2.1.287 or later. Mods are on by default, so there's nothing to turn on. The API can change between releases. Each time Claude Code loads a mod, it writes the type declarations for your build into the mod's `.claude-plugin/types/` folder, and those are the authority for your version.
需要 Claude Code 2.1.287 或更高版本。Mod 默认开启，因此无需手动启用。API 可能会在不同版本之间发生变化。每次 Claude Code 加载 mod 时，它都会将类型声明写入 mod 的 `.claude-plugin/types/` 文件夹中，这些声明是你当前版本的权威依据。
How a mod works
Mod 的工作原理
A mod is a Claude Code plugin whose behavior lives in a JavaScript or TypeScript module:
Mod 是一种 Claude Code 插件，其行为位于 JavaScript 或 TypeScript 模块中：
- The folder is a normal plugin, with a `.claude-plugin/plugin.json` manifest. - `hooks/hooks.json` names one module under `modules`. - The module exports `register(on, options)`. Inside it, `on(event, matcher?, hook)` adds a hook.
- 该文件夹是一个普通插件，包含一个 `.claude-plugin/plugin.json` 清单文件。 - `hooks/hooks.json` 在 `modules` 下命名了一个模块。 - 该模块导出 `register(on, options)`。在其中，`on(event, matcher?, hook)` 添加一个钩子。
Every hook has the same shape:
每个钩子具有相同的结构：
on("tool.call", { tool: "Bash" }, async ($, e, next) => {
// $ the mods API: ui, session, state, store, fs, process, clock, http, tool, command, model, ...
// e this event's input, as plain data
// next passes e to the other plugins and then to Claude Code's own behavior
return next(e);
});Hooks form a chain, like middleware. Yours runs, `next(e)` hands the event to the next plugin, and at the bottom Claude Code does what it would have done anyway. A hook can do one of three things:
钩子形成一条链，类似于中间件。你的钩子运行后，`next(e)` 将事件传递给下一个插件，而在最底层，Claude Code 会执行它原本就会做的操作。一个钩子可以执行以下三种操作之一：
*Figure: An event passes through your hook, then other plugins, then Claude Code. Each calls next(e) to pass it on, and the result flows back. A hook that answers returns without calling next.*
*图：一个事件穿过你的钩子，然后经过其他插件，最后到达 Claude Code。每个环节都调用 next(e) 将其传递下去，结果再反向流回。一个做出响应的钩子会直接返回，而不调用 next。*
| Move | How | Example | ||
|---|---|---|---|---|
| ----------- | ---------------------------------------------- | ------------------------------------------------------- | ||
| Observe | `const r = await next(e); /* look */ return r` | Record every file edit. Take a reading after each turn. | ||
| Rewrite | `return next({ ...e, command: safer })` | Change what the rest of the chain sees. | ||
| Answer | `return { deny: "…" }` without calling `next` | Refuse a tool call. Serve a command or a tool yourself. |
| 动作 | 方式 | 示例 | ||
|---|---|---|---|---|
| ----------- | ---------------------------------------------- | ------------------------------------------------------- | ||
| 观察 | `const r = await next(e); /* look */ return r` | 记录每次文件编辑。在每轮操作后读取状态。 | ||
| 重写 | `return next({ ...e, command: safer })` | 改变链条其余部分看到的内容。 | ||
| 回答 | `return { deny: "…" }` 且不调用 `next` | 拒绝工具调用。自行提供命令或工具。 |
The events cover tool calls, the prompt as submitted, turns starting and finishing, the session starting and ending, slash commands, and `ui.render`: every piece of the interface as it's drawn. The module runs in a sandbox of its own, with no DOM and no Node, so everything outside it goes through `$`.
这些事件涵盖工具调用、提交的提示词、轮次开始与结束、会话开始与结束、斜杠命令以及 `ui.render`：即界面绘制过程中的每一个部分。该模块在其自身的沙箱中运行，没有 DOM 也没有 Node.js，因此其外部的所有内容都通过 `$` 进行交互。
How this differs from settings hooks. A settings hook runs a shell command for each event and passes JSON over stdin and stdout. A mod is loaded once and stays in the session. It can keep state, draw UI that updates as events happen, and call back into Claude Code: open a pane, run a process, register a slash command, or register a tool the model can call.
这与设置钩子的区别在于：设置钩子为每个事件运行一个 shell 命令，并通过 stdin 和 stdout 传递 JSON。而 Mod 只加载一次并保留在整个会话中。它可以保持状态，绘制随事件发生而更新的 UI，并回调到 Claude Code：打开窗格、运行进程、注册斜杠命令，或注册模型可调用的工具。
Claude Code uses them itself. Some of Claude Code's own features are built as mods, including AGENTS.md support and the `/diff` pane beside the conversation. Their source, with tests, is in the public anthropics/claude-code repository under `mods/`, so you can read how the team builds them.
Claude Code 自身也在使用它们。Claude Code 的一些功能就是作为 Mod 构建的，包括 AGENTS.md 支持和对话旁边的 `/diff` 窗格。它们的源代码（含测试）位于公共仓库 anthropics/claude-code 的 `mods/` 目录下，你可以阅读团队是如何构建它们的。
Build your first mod: Token Weather
构建你的第一个 Mod：Token Weather
Token Weather reads how full the context window is after each turn and draws one line above the prompt: a weather icon, the percentage, the tokens used out of the window, a small chart of recent turns, and how much the last turn added.
Token Weather 会在每轮操作后读取上下文窗口的填充程度，并在提示词上方显示一行内容：一个天气图标、百分比、窗口中使用的 token 数量、近期轮次的小图表，以及上一轮增加了多少 token。
| Used | Forecast | ||
|---|---|---|---|
| ---------- | -------------- | ||
| under 25% | ☀ Clear | ||
| 25–49% | ☁ Cloudy | ||
| 50–74% | ☂ Showers | ||
| 75–89% | ☇ Storm | ||
| 90% and up | ↯ Compact soon |
| 已使用 | 预测 | ||
|---|---|---|---|
| ---------- | -------------- | ||
| 低于 25% | ☀ 晴朗 | ||
| 25–49% | ☁ 多云 | ||
| 50–74% | ☂ 阵雨 | ||
| 75–89% | ☇ 风暴 | ||
| 90% 及以上 | ↯ 即将紧凑 |
Here it is in a real session. Each turn reads more files, and the band fills from ☀ Clear to ☂ Showers to ☇ Storm:
以下是实际会话中的效果。每一轮会读取更多文件，状态条从 ☀ 晴朗变为 ☂ 阵雨，再变为 ☇ 风暴：
Video (Terminal): Token Weather in a full terminal session over three turns: 18%, then 67%, then 81% of a 200k window — A dark terminal window where each turn asks Claude to read more Python files, while the band above the prompt turns from yellow Clear to blue Showers to pink Storm.
视频（终端）：在完整终端会话中经历三轮的 Token Weather：分别为 200k 窗口的 18%、67% 和 81% —— 一个深色终端窗口，每一轮都要求 Claude 读取更多 Python 文件，同时提示符上方的状态条从黄色的 Clear 变为蓝色的 Showers，再变为粉色的 Storm。
Video (Desktop): Token Weather in Claude Code on desktop over three turns: 10%, then 54%, then 77% of a 200k window — The light Code tab of the Claude desktop app, where each turn asks Claude to read more of a weather-station service, its logs and readings, then its tests, while the band above the prompt box turns from yellow Clear to blue Showers to pink Storm.
视频（桌面端）：在桌面版 Claude Code 中经历三轮的 Token Weather：分别为 200k 窗口的 10%、54% 和 77% —— Claude 桌面应用的浅色 Code 标签页，每一轮都要求 Claude 读取更多关于气象站服务的代码、其日志和读数，然后是测试代码，同时提示框上方的状态条从黄色的 Clear 变为蓝色的 Showers，再变为粉色的 Storm。
The shortcut: let Claude build it
快捷方式：让 Claude 来构建
You can skip the six steps. Claude Code knows how to write mods, so you can describe the one you want and let it do the work. Start a session with `claude` and paste the prompt below:
你可以跳过这六个步骤。Claude Code 知道如何编写插件（mods），因此你只需描述你想要的功能，让它来完成工作。启动一个 `claude` 会话并粘贴以下提示词：
Make me a Claude Code mod called token-weather: a live forecast of my context window, shown in the band above the prompt.
What it should show, on one line:
- A weather icon and word for how full the context window is: under 25% ☀ Clear (yellow), 25–49% ☁ Cloudy (cyan), 50–74% ☂ Showers (blue), 75–89% ☇ Storm (magenta), 90% and up ↯ Compact soon (red).
- The percentage used, then the tokens used out of the window, like "134.4k / 200k".
- A small chart of the last 12 turns, drawn with ▁▂▃▄▅▆▇█.
- How much the last turn added, like "▲ +98.3k last turn".
It should update after every turn.Claude asks once whether to turn on hot reloading for the session. Allow it, and the band appears above the prompt when Claude's turn ends. From then on, every change reloads in place, so you can keep asking for tweaks ("make Storm start at 70%", "add the dollar cost at the end") and watch the band change. The mod loads only in this session, and its folder is cleaned up later, so to keep it, copy the folder out and install it like any plugin (Step 6).
Claude 会询问是否在本次会话中启用热重载。允许后，当 Claude 完成本轮响应时，状态条就会出现在提示符上方。此后，每次更改都会就地重新加载，因此你可以继续提出调整请求（例如“让 Storm 从 70% 开始”、“在末尾添加美元成本”），并观察状态条的变化。该插件仅在当前会话中加载，稍后会清理其文件夹；若要保留它，请将文件夹复制出来，并按常规插件的方式安装（第 6 步）。
Notice that the prompt only describes what you want to see. You don't need to know the API to write one. Claude Code's built-in guide for writing mods covers the how: where to keep state so it survives a reload, how to check the plugin with `claude plugin validate`, and which events to hook. Change the "What it should show" lines and it's your mod, not ours.
请注意，提示词仅描述了你希望看到的内容。你无需了解 API 即可编写插件。Claude Code 内置的插件编写指南涵盖了具体操作方法：如何将状态保存在重启后仍能保留的位置、如何使用 `claude plugin validate` 检查插件，以及应挂钩哪些事件。修改“What it should show”部分的内容，这就是你的插件，而非我们的。
If you'd rather see how it's put together first, or want to check what Claude wrote, read on.
如果你更想先看看它是如何组装的，或者想检查 Claude 写了什么，请继续阅读。
更进一步：量化金融体系
看懂新闻只是起点——沿量化金融路径，把它变成能交付的工程能力