Cache Clock：随时看清 Claude Code 提示缓存何时过期

Cache Clock 是一款显示 Claude Code 提示缓存状态的社区插件，作者是 Hamza Zafar（hamzafer），属于他的 claude-code-mods 合集。它在状态栏下方多显示一行。缓存处于热状态时这一行为绿色，形如 cache ● 1h ██████████ 59m left · hit 48% · misses 0：缓存有效期（5m 或 1h）、一条十格的剩余时间条、剩余时间、命中率和未命中次数。

当剩余时间不足有效期的 20% 时，这一行变黄。缓存过期后变红：cache ○ cold · next message re-caches 82k tokens，如果 Claude Code 报告了上一次未命中的原因，也会一并附上。意义在于：发送消息之前就能知道，这条消息会命中缓存，还是要花钱重建整个前缀。

这些数字不是插件算出来的。Claude Code 从 2.1.251 起会向状态栏命令发送一个 prompt_cache 对象，插件只负责格式化。插件无法注册状态栏，所以它添加了 /cache-clock 命令：setup 把 statusLine 指向插件的脚本，remove 把一切恢复原状。如果你已经有状态栏，它会保留，缓存这一行放在它下面。

录屏中，我们在小型演示项目里启动加载了该插件的 Claude Code，状态栏已预先指向插件的脚本；我们有意跳过了 /cache-clock setup 这一步，以免演示改写录制者自己的 ~/.claude。随后让 Claude 读取 README.md，用一句话描述这个项目。这一轮运行期间，输入框下方有一行绿色的 cache ● 1h，条是满的，显示 59m left 和 hit 0% · misses 0。这一轮结束后，同一行更新为 hit 48% · misses 0。

使用安装区块中的任意一种方式；它们都直接从作者自己的插件市场安装。然后在会话中运行 /cache-clock setup。这一行会在 Claude 下一次回复后出现，单独运行 /cache-clock 可以查看它是否已开启。

hooks/register.ts 注册命令并完成设置。随插件发布的 statusline/cache-clock.mjs 是 Claude Code 在每次状态栏刷新时运行的脚本。它从 stdin 读取 JSON，如果保存了你原来的命令就先运行它，然后输出缓存这一行。纯函数格式化器位于 statusline/render.mjs：

export function render(input, nowSeconds) {
  const cache = input?.prompt_cache
  if (!cache || typeof cache !== 'object') return ''
  if (cache.caching_observed === false) return ''

  const left = typeof cache.expires_at === 'number' ? cache.expires_at - nowSeconds : null
  const isWarm = cache.warm !== false && left !== null && left > 0
  return isWarm ? warmLine(cache, left) : coldLine(cache)
}

只要 expires_at 已过，这一行就视为冷缓存，即使输入在生成时标记为热。setup 把两个脚本写到 <config dir>/cache-clock/，而不是插件目录，因为插件目录会随每个版本变化。下次会话开始时，如果状态栏是该插件的，refreshScripts 会用新版本覆盖这些副本。setup 会把 refreshInterval 设为 30 秒（除非你原来的值更短），这样倒计时在两次回复之间也会走动。

没有任何选项。/cache-clock setup 和 /cache-clock remove 是仅有的开关。若要改变外观，请编辑 render.mjs：BAR_CELLS 控制条的宽度，WARN_SHARE 控制变黄的临界点（默认 20%），文件顶部是颜色转义码。请编辑 <config dir>/cache-clock/ 下的副本；在已设置的状态下，插件会在下次会话开始时用发布版本覆盖它。

在运行之前，我们读过了插件会执行的每一个文件：.claude-plugin/plugin.json、hooks/hooks.json、hooks/register.ts、两个状态栏脚本以及测试。没有 package.json、安装脚本、打包或压缩代码，也没有二进制文件。仓库带有 MIT 的 LICENSE。

• 仅在你要求时修改设置。 安装和会话开始时除了刷新自己的脚本外不会写入任何内容。/cache-clock setup 会写入 Claude 配置目录（或 CLAUDE_CONFIG_DIR）下的 settings.json；当状态栏来自项目设置时，则写入 <project>/.claude/settings.local.json。它还会在 <config dir>/cache-clock/ 下写入脚本和备份文件 setup-<hash>.json。/cache-clock remove 会恢复之前的 statusLine，除非你在设置后又改过它。它拒绝改动受管理（policy）设置或 --settings 提供的状态栏，遇到无效的设置 JSON 也不会去动。
• 每次刷新都会运行一条命令。 设置之后，Claude Code 会运行 node "<config dir>/cache-clock/cache-clock.mjs"。该脚本用相同的输入通过 shell 运行你之前的状态栏命令（spawnSync(..., { shell: true })，超时 5 秒）。setup 本身会运行 node --version 来检查 Node 是否存在。
• 没有网络、没有遥测、不调用模型、没有守护进程。 它读取 HOME 和 CLAUDE_CONFIG_DIR 只是为了找到配置目录，不读取任何令牌或凭据。
• 没有提示注入，也没有拦截类钩子。 它只注册了 session.start 和自己的命令，不向提示词或工具结果中添加任何内容。
• 要求： PATH 中有 Node，Claude Code 为 2.1.251 或更高。

claude plugin validate 没有报告任何错误或警告，作者的 25 个测试在 Claude Code 2.1.296 上全部通过。

已在 macOS 上使用 Claude Code 2.1.296 检查（validate、测试和演示）。如果这一行没有出现：

• 运行 /cache-clock，应当显示 “cache-clock is on”。
• 先发送一条消息。在 prompt_cache 到达之前这一行是空的；服务商报告没有缓存时也是空的。
• claude --version 为 2.1.251 或更高，并且在同一个终端中 node --version 可以运行。
• 你的状态栏不是由受管理设置或 --settings 指定的；setup 会拒绝改动这些。
• 在已经运行的会话中执行 setup 后，等待下一次回复或 30 秒的刷新。