Addy Osmani 讲解如何上手 Claude Code Mods

Addy Osmani· @addyosmani · X·2026-10-28 14:15· 20 分钟前精选AI 评分72

AI 导读

Addy Osmani 发布 Claude Code Mods 上手指南，说明 mods 是运行在会话中的 JavaScript/TypeScript 文件，可通过 hooks 观察事件、改写行为或渲染自定义界面。

推荐理由

作者亲自讲解 Claude Code Mods 的机制与上手方法，覆盖三个可复用的示例 mod，读者可照做搭建自己的定制界面。

正文 · 原文

https://x.com/i/article/2115184482940784640

【X 长文】Claude Code Mods 上手指南

Mods 几周前在 Claude Code 中发布，我分享这份指南，帮助大家更轻松地上手。

Mods 是运行在 Claude Code 会话中的小型 JavaScript 或 TypeScript 文件。它们让你能够响应事件、修改 Claude Code 的行为，或在终端和桌面应用中渲染你自己的界面。这是 Lydia 制作的一段约 3 分钟的介绍 mods 的视频：

我最喜欢 mods 的一点是，无需学习其 API 就能创建。运行 claude 并描述你希望它创建的 mod。在 Claude 写入文件时批准这些文件，在被询问是否启用热重载时选择是，你的 mod 就会在回合结束时显示出来。

在本指南中，你将看到 mods 能力的高层概览，以及如何提示 Claude Code 创建一个 mod。你还会学到如何持久化、分发和安装你自己的 mods。顺便说一句，这份文档还有一个代码更密集的版本，不过你也可以直接让 Claude 帮你构建 mods。

虽然 Claude Code 已经允许你自定义大量行为，例如配置设置、权限策略、斜杠命令、技能和状态行，但 mods 让你能做更多事情。借助 mods，你可以改变或覆盖 Claude Code 的行为，或渲染你自己的自定义界面。大家一直在兴致勃勃地构建 mods，包括多人版 Doom！

那相当不错。借助 mods，你可以为自己的工作流打造量身定制的体验。创建一个持续显示、供你监控的界面。为高风险命令设置安全网。按你喜欢的阅读方式设计自己的 diff 渲染器。

在我们的演示中，首先从 Token Weather 开始，这个 mod 会在提示符上方逐回合显示上下文窗口的预测。然后我们会看两个更复杂的 mod——Blast Radius 和 Replay Theater，进一步探索 mods 的可能性。

如果你想随时查看这三个 mod 的完整代码，可以在 anthropics/claude-code-playground 中找到它们。

Mods 的工作原理

从技术层面讲，mods 是与插件捆绑的 hooks。每个 hook 都能看到会话中发生的所有事件，例如工具调用发生时、提示提交时、回合开始和结束时、会话开始和结束时、斜杠命令执行时，以及 UI 任何部分的每次渲染。

Hooks 像中间件一样串联起来。当事件发生时，它会先经过你的 hook，再经过其他插件，最后才到达 Claude Code 并执行其默认操作。

当事件发生时，hook 可以做三件事之一：

- 观察：允许事件继续并观察结果。例如，hook 可以记录每次文件被修改的时间，或在每个回合后拍摄快照。

- 改写：为剩余的 hooks 更改事件。例如，hook 可以向提示中添加文本，或更改工具调用的输入。

- 应答：自行处理事件，使默认行为不运行。例如，hook 可以拒绝工具调用或应答命令。

在思考一个 mod 做什么以及如何向 Claude 提出需求时，这些术语很有帮助：“拒绝这类命令”是一个答案，而“每轮之后拍个快照”则是一个观察。

mod 与 settings hooks 的区别

settings hook 是在每次事件发生时运行的 shell 命令。mod 则是一次性加载到会话中，并维护自己的状态和 UI，可以响应事件进行更新。mod 还可以回调 Claude Code。例如，它可以打开一个窗格、启动一个进程，或注册一个可由模型调用的斜杠命令或工具。

我们用 mod 来实现 Claude Code 自身的一些功能，例如 AGENTS.md 支持和 /diff 窗格。代码和测试可在公开的 anthropics/claude-code 仓库的 mods/ 目录中找到。

编写你的第一个 mod：Token Weather

Token Weather 会在每轮结束后，在提示符上方的条带中显示一行内容，告诉你上下文窗口有多满，其中包括一个天气图标和已使用上下文窗口的百分比。它还会显示已从上下文窗口使用的 token 数量、一个显示最近几轮上下文窗口变化趋势的迷你图表，以及自上一轮以来新增的 token 数量。

下面是该 mod 运行时的演示。终端会话显示读取的文件逐渐增多，条带颜色从 ☀ Clear 变为 ☂ Showers 再变为 ☇ Storm：

告诉 Claude，看它为你构建

Claude Code 内置了创建 mod 的方式，所以你只需描述想要的 mod，Claude 就会为你制作。启动一个 claude 会话，并将以下内容粘贴进去：

在 Claude 写入文件时批准这些文件，然后在 Claude Code 询问是否为该会话启用热重载时回答 yes。该轮结束时，条带会显示在提示符上方。

你会注意到提示词从未提及事件、状态或 API。它只说明你想看到什么。Claude Code 自带编写 mod 的指南，所以它已经知道该怎么做：把状态保存在哪里以免重载时被清除、如何用 claude plugin validate 检查插件、要挂钩哪些事件。

修改“它应该显示什么”部分，它就是你的 mod，而不是我们的。

通过提问来迭代

从那时起，你可以随时更改，无需重启。要求“让 Storm 从 70% 开始”或“在末尾加上美元成本”，条带就会在你眼前更新。对我来说，这种快速循环正是 mod 有趣的主要原因。

如果 mod 的视觉效果消失了，请运行 claude --debug 并查找一行说明某个 hook 返回了未通过验证的树的内容。

API 可能在不同版本之间发生变化。当 Claude Code 加载 mod 时，它会将你的构建所需的类型声明写入该 mod 的 .claude-plugin/types/ 文件夹，因此请将这些视为你所用版本的参考。

保留下来

以这种方式构建的 mod 仅对当前会话加载，其文件夹稍后会被清理。要保留它，请将该文件夹从 ~/.claude/dev-mods/<session-id>/ 复制出来，并像安装任何其他插件一样安装它，下一节将介绍这一点。

如果你想看最终产品的示例，可以在 anthropics/claude-code-playground 中查看完整的 Token Weather mod。

发布和安装 mod

mod 就是 Claude Code 插件，因此发布和安装它们与任何其他插件相同。要发布一个 mod，只需将其放入 GitHub 仓库并在其中包含一个 marketplace 文件；这将使其成为你可以发布到的 marketplace，你可以用常规方式向其推送更新。

要安装一个 mod，请在 Claude Code 中使用三条命令：

- /plugin marketplace add 加上 GitHub 仓库（例如 your-org/my-mods）

- /plugin install 加上该市场中的 mod 名称（例如 token-weather@my-mods），然后选择作用域

- 如果 mod 没有自行启动，请使用 /reload-plugins

如果你愿意，可以把你的 mod 作为插件添加到 Claude 目录中；在 claude.ai/directory/manage 提交它，即可被他人发现，而无需提供仓库链接。

安全性

Mod 是在你的本地机器上、以你的权限在 Claude Code 中运行的代码。Mod 没有沙箱隔离：它们可以读取你的文件和密钥、启动进程、发起网络请求并批准工具调用。Mod 由其作者编写，而非 Anthropic。

就像对待任何软件包一样，请阅读源代码，并且只安装来自你信任的人的 mod。要在安装前查看某个 mod 会挂钩和调用什么，请对其文件夹运行 claude plugin validate。

另外两个示例

到目前为止，Token Weather 只涉及观察和渲染。接下来的两个 mod 涉及事件、面板和用户交互。你可以在 anthropics/claude-code-playground 中查看两者的完整代码：Blast Radius 和 Replay Theater，每个都附有说明其制作方式的 README。

Blast Radius：为危险命令预览更改

Blast Radius 会拦截 Claude 对 Bash 的潜在危险调用（例如 rm -rf、git reset --hard、git clean、force push、数据库迁移），并计算它们会产生什么效果。随后会打开一个带有 Proceed 或 Cancel 按钮的面板。

- 如果你按 2，Claude 会收到带有原因的拒绝。

- 如果你按 1，命令会照常运行。

实际上，这就是之前的“answer”动作。Blast Radius 会根据每个工具的 dry run 输出（例如 git status --porcelain、git clean -n）汇编报告。它会等待按钮按下，或者在你按 Esc 时取消。

如果终端足够宽，面板会停靠在对话记录旁边的一侧。如果不够宽，Blast Radius 会在提示符上方渲染报告。同一时间只能有一个 mod 使用该区域，因此如果另一个 mod 占用了它，按钮可能不会出现，并且命令会在 10 分钟后被拒绝。

请把它看作安全网，而不是真正的防火墙。它读取命令文本，因此 $(…)、别名以及调用 rm 的脚本都能绕过它。如果你想要硬性阻止，请使用权限规则。

Replay Theater：在回合结束时回顾发生了什么

当一个回合正在运行时，Replay Theater 会监视所有 Edit 和 Write 调用，以查看哪些文件发生了更改以及更改成了什么。在回合结束时，你会在提示符上方看到一条消息，告知你可以重放这些更改。输入 /replay（或按 ctrl+x 然后按 Tab 聚焦该区域，再按 r），你会看到一个面板，其中以 diff 形式显示每次编辑的更改。它还会有一个步骤编号列表以及 Prev、Next 和 Close 按钮。

它从不阻止或影响编辑，只是进行观察。

每个回合都有自己的重放，子代理的编辑会包含在主回合的重放中。面板的位置取决于空间：在全屏模式下停靠在右侧，在 80 列时内联显示在提示符上方。

我喜欢的几个社区 mod

可以想象，自我们发布以来，出现了许多我从未想到过的创作。以下只是我最喜欢的几个。

Daniel Avila 的 Stack viewer。一个 /stack mod，用于显示你的 Claude Code 会话中所有已安装和可用的工具：skills、subagents、commands、hooks、MCP servers、plugins。请查看帖子中的视频和安装说明。

cc-stretch，作者 pro-vi。Claude Code 的 Stretchtext 模组。当 Claude Code 回应时，它会简短回应，你点击的任何链接短语都会展开到完整长度。这是对旧超文本概念的一种美丽而现代的诠释。

Mindful Claude，作者 halluton。当 Claude 开始工作时，你会在提示上方看到一个动画，帮助你深呼吸。这也被 XDA 的一篇文章报道过。

RemCTL，作者 Federico Viticci。一个 Apple Reminders CLI 和 Claude Code 插件。Today 模组会在提示上方显示你今天的提醒事项。

你会制作什么模组？

这里的三个演示都始于同一个问题：我有多少上下文？即将运行什么命令？Claude 刚刚改了什么？你的问题很可能与我的不同，你的模组也会不同。

遵循 Token Weather 演示中的相同流程：告诉 Claude 你想看到什么、在什么条件下，把实现细节留给 Claude。享受另一个游戏模组，并在下方链接到更多模组！

分享你的模组！

一旦你开发出一个每天都会使用的模组，请花点时间发布一个它运行中的视频，让其他开发者看到什么是可能的。（你也可以将插件添加到市场并分享链接。任何喜欢你的模组的人都可以用几个简单命令安装它。）

我们迫不及待想看到你构建的东西！

来源：Addy Osmani · x.com