Cache Clock Claude Code mod: watch your Claude Code prompt cache expire

Cache Clock is a community mod by Hamza Zafar (hamzafer), part of his claude-code-mods collection. It shows the state of your Claude Code prompt cache as one line under the status line. While the cache is warm the line is green and reads like cache ● 1h ██████████ 59m left · hit 48% · misses 0: the cache lifetime (5m or 1h), a ten-cell bar of how much of it is left, the time remaining, the hit ratio and the miss count.

When less than 20% of the lifetime is left, the line turns yellow. Once the cache has expired it turns red: cache ○ cold · next message re-caches 82k tokens, with the cause of the last miss added when Claude Code reports one. The point is to see, before you send a message, whether it will be served from the cache or will pay to rebuild the whole prefix.

The figures are not computed by the mod. Claude Code sends a prompt_cache object to the status line command (from 2.1.251), and the mod only formats it. Plugins cannot register a status line, so the mod adds a /cache-clock command: setup points statusLine at the mod's script and remove puts things back. If you already have a status line, it stays and the cache line goes under it.

Cache Clock only displays the cache state. If you also want the cache kept warm with keep-alive requests and a prompt before an expensive cold send, see Cache Keeper.

The recording starts Claude Code with the mod loaded in the small demo project, with the status line already pointed at the mod's script; the /cache-clock setup step is skipped on purpose so the demo does not write to the recorder's own ~/.claude. It asks Claude to read README.md and describe the project in one sentence. While the turn runs, a green cache ● 1h line with a full bar, 59m left and hit 0% · misses 0 sits under the prompt. When the turn finishes, the same line updates to hit 48% · misses 0.

Use any of the methods in the install block; they install straight from the author's own marketplace. Then run /cache-clock setup in a session. The line appears after Claude's next reply, and /cache-clock alone tells you whether it is on.

hooks/register.ts registers the command and does the setup. The shipped statusline/cache-clock.mjs is what Claude Code runs on every status line refresh. It reads the JSON from stdin, runs your original command if one was saved, and prints the cache line. The pure formatter is in 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)
}

The line counts as cold as soon as expires_at has passed, even if the input said warm when it was built. setup writes the two scripts to <config dir>/cache-clock/ instead of the plugin folder, because the plugin folder changes with every version. On the next session start, refreshScripts copies fresh versions over them if the status line is the mod's. setup sets refreshInterval to 30 seconds unless yours is already shorter, so the countdown moves between replies.

There are no options. /cache-clock setup and /cache-clock remove are the only switches. To change the look, edit render.mjs: BAR_CELLS for the bar width, WARN_SHARE for the point where the line turns yellow (20% by default) and the color escape codes at the top. Edit the copy under <config dir>/cache-clock/; the mod overwrites it with the shipped version on the next session start while it is set up.

We read every file the plugin runs: .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.ts, both status line scripts and the tests. There is no package.json, install script, bundled or minified code, or binary. The repository has an MIT LICENSE.

• Settings change, only on request. Nothing is written at install or session start except a refresh of its own scripts. /cache-clock setup writes settings.json in your Claude config folder (or CLAUDE_CONFIG_DIR), or <project>/.claude/settings.local.json when the status line comes from project settings. It also writes the scripts and a setup-<hash>.json backup under <config dir>/cache-clock/. /cache-clock remove restores the previous statusLine, unless you changed it since. It refuses to touch managed (policy) or --settings status lines, and leaves invalid settings JSON alone.
• Runs a command on every refresh. After setup, Claude Code runs node "<config dir>/cache-clock/cache-clock.mjs". That script runs your previous status line command through a shell (spawnSync(..., { shell: true }), 5 s timeout) with the same input. setup itself runs node --version to check Node is present.
• No network, no telemetry, no model calls, no daemon. It reads HOME and CLAUDE_CONFIG_DIR only to find the config folder. No tokens or credentials are read.
• No prompt injection and no gating hooks. It only registers session.start and its own command. It adds nothing to prompts or tool results.
• Requirements: Node on your PATH and Claude Code 2.1.251 or later.

claude plugin validate reported no errors or warnings, and the author's 25 tests passed on Claude Code 2.1.296.

Checked with Claude Code 2.1.296 on macOS (validate, tests and the demo). If the line does not show up:

• Run /cache-clock. It should say "cache-clock is on".
• Send one message first. The line is empty until prompt_cache arrives, and also when the provider reports no caching.
• claude --version is 2.1.251 or later, and node --version works in the same terminal.
• Your status line is not set by managed settings or --settings; setup refuses to change those.
• After setup in a session already running, wait for the next reply or the 30-second refresh.