cache-clock: the prompt cache, on your status line

[hamzafer]

What

A new mod, cache-clock: a prompt-cache line under your status line, from the prompt_cache figures Claude Code sends to status line commands (2.1.251+).

cache ● 1h ███████░░░ 38m left · hit 91% · misses 0
cache ● 5m ██░░░░░░░░ 53s left · hit 36% · misses 1
cache ○ cold · next message re-caches 82k tokens · ttl expired 5m

• Green while warm, yellow under 20% of the lifetime, red once cold with the re-cache token count and the last miss cause
• Shows nothing until prompt_cache appears; skips fields an older version doesn't send

How it hooks in

Plugins can't register a status line, and prompt_cache isn't exposed to plugin hooks, only to the status line command.

• /cache-clock setup copies a small Node script to <config dir>/cache-clock/, saves the current status line, and points statusLine at the script with refreshInterval: 30. The script runs the original command with the same stdin, prints its output unchanged, then the cache line
• /cache-clock remove restores the settings exactly
• Writes to the file the status line comes from; a project's shared settings get a settings.local.json override instead; managed settings are left alone
• On session start, the copied scripts catch up with a newer mod version

token-weather 0.2.1

Hides its estimated countdown while cache-clock is set up, so the cache isn't shown twice.

Checked

• claude plugin validate and claude plugin test for both mods (22 + 23 tests)
• The real script under Node on warm, about-to-expire, cold and no-prompt_cache inputs
• Live setup → status line → remove round trip in a throwaway config dir

🤖 Generated with Claude Code

[hamzafer]

Review notes

Sonnet review, addressed in 15988d8:

• Shared setup.json across settings files: fixed. State is now kept per settings file (setup-<key>.json), and the status line command carries its key. Setups in the user settings and in projects no longer overwrite each other's original. Tests added.
• Subfolder cwd picked the wrong local settings: fixed. It now uses $.session.root(). Tests added.
• Sync stdin read could hit EAGAIN: fixed. stdin is now read as a stream.
• Unescaped config path / unset HOME: fixed. The path is escaped for sh, and setup fails clearly without HOME. Tests added.
• Remove wording in docs: fixed. The docs now say a status line changed by hand is left alone.
• Not changed:
  • token-weather hides even when cache-clock shows nothing. Only on Claude Code older than 2.1.251 (setup warns), or before the first reply, when token-weather has no countdown either.
  • warm: true with null expires_at. Per the docs, expires_at is only null when the last response had no cache tokens, and then warm is false.
  • ttl expired 5m sample. Correct as is: it comes from the ttl_expired_5m cause.
• Tried and dropped: a check after writing settings. The engine doesn't re-read settings right away, so the check fired every time in a live run.

Codex (gpt-5.6-luna): no actionable issues found.

Verified: 25 cache-clock tests and 23 token-weather tests pass, and a live setup → status line → remove round trip in a throwaway config dir works.