Claude Code 悄悄上线了个 mods 系统：hook 还在事后打日志，mod 已经在事件里改写它——做个上下文天气预报只要 80 行

Claude Code 2.1.287 在 2026 年 10 月 1 日默认开启了一个叫 mods 的能力：用一个几十行的 JavaScript/TypeScript 模块，就能在事件发生之前改写 Claude Code 的行为，还能直接往终端里画自己的界面——官方示例只用 80 行，就把上下文余量画成了一条「天气预报」。

在 mods 之前，hooks 已经到天花板了

Claude Code 早就有 hooks：事件触发时起一个子进程，通过 stdin/stdout 传 JSON。它能做的事很有限：

关键差别是时序：hook 只能在事件发生之后做点补救（记条日志、拒绝一次调用），而 mod 拿到的是一个 next 函数——调用它事件才往下走，甚至可以不调用它、自己返回一个结果，让 Claude Code 根本收不到原始事件。

mod 的 API：三个参数，三种动作

mod 本质是随插件分发的一个模块：插件目录里放 .claude-plugin/plugin.json，hooks/hooks.json 指向一个导出 register 函数的模块，模块对事件挂监听：

// mods/token-weather/mod.js —— 事件监听骨架
export function register(on) {
  on('tool.call', ($, e, next) => {
    // 1. 观察：放行后再看结果
    const result = next(e)
    // 2. 改写：下游看到的是被改过的事件
    // return next({ ...e, command: 'git status --dry-run' })
    // 3. 否决：不调 next，自己返回，事件到不了 Claude Code
    // return { ok: false, message: '这个命令被 mod 拦下了' }
    return result
  })
}

三个参数分别是 $（mod API：UI、状态、session、文件系统、进程控制）、e（事件数据）和 next（交给下一个 mod 或交给 Claude Code 本体）。可监听的事件覆盖工具调用、提交的 prompt、轮次与会话的起止、slash 命令，以及每次界面绘制都会触发的 ui.render；多个 mod 挂同一事件时按加载顺序成链，先加载的先看到。

Token Weather：80 行把上下文余量画成天气

官方入门指南（Addy Osmani 撰写，2026-10-01 发布在 claude.dev）用一个约 80 行的示例 mod 走完全程。它在每轮结束后读 $ session.usage()，在输入行上方画一条状态带：

• 200,000 token 窗口用到 18% → 显示 ☀️ Clear
• 用到 67% → ⛅ Showers
• 用到 81% → ⛈ Storm（提示快触发压缩了）

同一行还带最近几轮的迷你走势和「上一轮新增多少 token」。此前想知道「上下文还剩多少」只能靠 /context 手动查，现在它常驻在提示行上方实时刷新——这就是 hook 做不到的事：它没有 UI，也没有跨轮状态。

指南还给了两个更大的例子：Blast Radius 拦截 rm -rf、git reset --hard、强制推送这类 Bash 调用，先跑 dry-run 量出影响面，再弹一个带 Proceed/Cancel 的面板；Replay Theater 记录一轮里的 Edit/Write，注册 /replay 命令逐步回放 diff。有意思的是，AGENTS.md 支持和 /diff 面板本身就是 Anthropic 用 mods 实现的，源码就放在公开的 claude-code 仓库 mods/ 目录下。

边界与风险：mod 和 Claude Code 权限一样大

这是必须先说清楚的一点：mod 是发布者（不是 Anthropic）写的、以 Claude Code 同等权限在本机运行的代码。Anthropic 的建议和审 npm 包一样——先读源码，只装信任的发布者。团队和企业版有兜底：托管设置的机器会先加载 sec-default guard，防止用户安装的 mod 覆盖权限拒绝规则。另外官方明说 mods 的 API 可能随版本变动，每个构建写进 .claude-plugin/types/ 的类型声明才是当期权威。

下一步：三步上手

1. 确认版本：claude --version ≥ 2.1.287（mods 默认开启，旧版没有）
2. 建一个最小插件：claude plugin create 起骨架，hooks/hooks.json 指向你的 mod 文件，本地用 claude plugin validate 和 claude plugin test 校验
3. 最快的路径其实是直接对 Claude Code 描述你要的 mod——它写完会热更新进当前会话，先跑 Token Weather，再改自己的

（来源：claude.dev《Changing how Claude Code looks and behaviors》Addy Osmani 2026-10-01；Boris Cherny X 公告 2026-10-01；Anthropic GitHub function hooks 讨论 2026-09-03；tarekalaaddin.com 深度解析 2026-10-06；pivotnews/agihunt 报道）