用量告警 hook —— Claude 用量阈值 macOS 通知

定位

在 5 小时 / 7 天用量窗口越过阈值时，发一条 macOS 通知，提醒你快到限额了。仅 macOS，需订阅账号（Pro/Max）。

这是一个 hook（挂在 Stop 事件），随 vft-kit 插件自动注册，不用你写 settings.json。但它需要把「用量数据管道」接上（接通 claude-hud 落盘快照）才会真正告警。

这是理解这个 hook 的关键：官方 hook 事件的 payload 里不含任何用量数据。整个 Claude Code 里，唯一能拿到 rate_limits（限额百分比、重置时间）的地方是 statusline。

所以这个 hook 不直接读用量，而是读一份由 statusline 落盘的快照文件。这就需要 claude-hud 这个状态栏插件开启快照写入：

// ~/.claude/plugins/claude-hud/config.json
{
  "display": {
    "externalUsageWritePath": "/Users/<你>/.claude/usage-snapshot.json"
  }
}

claude-hud 侧只要这个 path 非空就开始落盘（每 ~30s 节流写一次），无额外开关。hook 端读这个快照，越过阈值就弹通知。没配这条、或用的是 API key（按量付费，没有限额窗口）时，hook 静默退出，不影响会话。

早期版本靠一个 usage-alert-setup skill 一键接通，现已移除——ai-helper 原生支持用量告警，手动接通也只两步。

装 jq（hook 本体的硬依赖，没有则静默退出）：brew install jq。
往 claude-hud 的 config.json 写快照路径（与 usage-alert.sh 默认读取路径 ~/.claude/usage-snapshot.json 指同一文件才能联动）：

// ~/.claude/plugins/claude-hud/config.json
{
  "display": {
    "externalUsageWritePath": "/Users/<你>/.claude/usage-snapshot.json"
  }
}

改完 重启会话（claude-hud 才会重载 config、开始落盘）；仅 Pro/Max 有限额窗口才会告警，API key 账号快照为空、不告警（正常）。

在 ~/.claude/vft-kit/usage-alert-config.json 建一份配置（不存在时 hook 用内建默认），直接编辑，改后重启会话生效：

{
  "thresholds": [70, 75, 80, 85, 90, 95, 100],
  "sound": "Glass",
  "maxAgeSeconds": 600,
  "snapshotPath": "~/.claude/usage-snapshot.json"
}

thresholds：越过哪些百分比时告警。每档只在当前达到的最高档告警一次（避免 92% 同时触发 70 和 90 两条）。想少打扰就精简成 [80, 95]。
sound：macOS 系统音名（Hero / Basso / Glass / Ping…）。
maxAgeSeconds：快照超过这个秒数就视为过期、不告警（默认 600）。
snapshotPath：必须与 claude-hud 的 externalUsageWritePath 一致。

取值优先级：环境变量（CLAUDE_USAGE_THRESHOLDS / CLAUDE_USAGE_SNAPSHOT）> 配置文件 > 内建默认。env 用于临时覆盖，长期自定义改配置文件。

告警去重键含 resets_at（限额窗口的重置时间）：同阈值、同窗口只告警一次；窗口一翻新（重置时间变了），同阈值可再次告警。state 文件在 ~/.claude/usage-alert-state，不会无限增长（超过 50 行自动截断）。

跑几个 turn 后：

cat ~/.claude/usage-snapshot.json   # 应能看到 five_hour / seven_day 的 used_percentage

有数据即管道通了；越过阈值时会弹「Claude 用量告警」通知。