feat(widgets): add prompt cache miss widgets - #770

What

Four new Cache widgets show the prompt cache statistics Claude Code reports for the main conversation:

Why

A cache miss re-sends content the prompt cache already held, so the whole prefix is written to the cache again. That's what makes a session's usage jump with nothing else changing: an MCP server connecting (the tool list changes), the system prompt changing, or coming back after the cache's 5-minute lifetime ran out. Until now the only place to see it was /usage.

Since 2.1.251, Claude Code sends these statistics to the status line command as prompt_cache, the same figures /usage shows on its "Prompt cache (main)" line. Since 2.1.260 it also reports the likely cause of the last miss. From the status line docs:

"prompt_cache": {
  "requests": 14,
  "misses": 2,
  "miss_recache_tokens": 310200,
  "last_miss_at": 1738425230,
  "last_miss_cause": { "causes": ["tools_changed"], "tools_added": 2, "tools_removed": 0 },
  "recache_tokens_if_cold": 45000
}

How

• Payload only. The widgets read prompt_cache from the status line payload: no transcript scan and no network call. Without it they render nothing. That covers Claude Code before 2.1.251 and the time before the session's first API response.
• Causes in plain words. tools_changed reads "tools changed (+2)", with the tools added and removed. system_prompt_changed reads "system prompt changed (+120 chars)". ttl_expired_5m reads "5m TTL expired". likely_server_side reads "likely server side". A cause added later shows with underscores turned into spaces. Several causes are joined with commas. A miss Claude Code couldn't diagnose (last_miss_cause: null, or Claude Code before 2.1.260) reads "cause unknown".
• When each renders. Last Cache Miss renders nothing until the session's first miss. Cache If Cold renders nothing while Claude Code has no figure, as right after a compaction. Cache Misses and Cache Miss Tokens show zero by default and can hide while the session has no misses (h, zero).
• Formats. Token amounts use the same formatter and number format option as Cache Read and Cache Write. The miss age uses the timers' compact duration (3m, 1h3m), and anything under a minute reads "just now".
• Shared code. One small shared module, widgets/shared/prompt-cache.ts, reads the object and words the causes. The widgets are four plain classes like their neighbors.
• Schema. prompt_cache joins StatusJSON. A field in a shape this version doesn't know is dropped instead of rejecting the payload, so a future change to the object can't blank the status line.
• Builds on fix(cache-timer): use Claude Code's reported cache expiry when present #576. fix(cache-timer): use Claude Code's reported cache expiry when present #576 added part of prompt_cache (warm, caching_observed, ttl, expires_at, hit_ratio, recache_tokens_if_cold) for Cache Timer. Those fields keep their names and types, and the schema adds the rest of the object around them. Cache Timer's code and tests are unchanged.

Demo

Adding the four widgets with the picker's search. The preview shows their samples, the docs' example session:

Powerline

Plain

Piped through the CLI in four situations: early in a session, a miss from two added tools, a miss after the 5-minute TTL expired, and a long session whose last miss had two causes. All data is made up.

Powerline

Plain

Testing

• On main as of [low] perf(claude-status): hold a lock while the status page fetch is in flight #635 and [medium] perf(git-review): key the PR cache through the cached runGit #639 (62a371b): merges cleanly, bun run lint is clean, and bun test gives 3738 pass, 0 fail. The built CLI under Bun 1.4.4 and Node 26.13.0 matches main in plain and Powerline mode with the baseline configs, and the TUI opens and exits cleanly.
• bun run lint passes. bun test: 3203 pass, 0 fail.
• 45 new tests:
  • StatusJSON: every documented field, documented nulls, and malformed fields dropped while the rest parses.
  • The shared module: each cause's wording, zero counts left out, several causes, unknown and missing causes, and age formatting.
  • The widgets: labeled and raw output, zero misses with and without the hide state, missing fields, previews, number format, and registration.
• Under Node (Vitest), the three new or changed test files pass 45 of 45. Across the full suite, this branch fails the same 18 files as main (spying on Node built-ins), plus ItemsEditor.test.ts's "edits a widget label…". That test is an existing timing flake: it uses fixed 25 ms sleeps, and it passed 3 of 3 runs in isolation.
• The built CLI under Bun 1.4.2 and Node 26.10.0 gives byte-identical output in plain and Powerline modes. I checked payloads with no prompt_cache, zero misses, several causes, a null cause, an unknown cause, a null recache_tokens_if_cold, and malformed fields. With the baseline configs it matches main, and the TUI opens and exits cleanly under both runtimes.