Add cache health to statusline

To add cache health monitoring to a custom statusline script for Claude Code, tracking the ratio between cache reads (cheap, reused tokens) and cache creation (expensive, rebuilding tokens). The implementation uses a JSON state file to detect consecutive zero-read checks, displaying a "CACHE MISS" warning in red when the cache is completely thrashed (3+ consecutive zero reads) or showing the cache hit percentage in green, yellow, or red based on performance. A broken cache means users pay full input token prices instead of receiving the ~90% cache discount, and the author notes that certain workflows like batch tool calls can consistently thrash the cache.

Add a cache health indicator to your Claude Code statusline If you're using a custom statusline script, you can add cache health monitoring to catch when your prompt cache is getting thrashed. Here's what to add and what it means. What it tracks: The ratio between cache read input tokens cheap, reused from cache and cache creation input tokens expensive, rebuilding cache . When cache reads drop to zero while creation stays high, you're paying full price every turn instead of getting the ~90% cache discount. Step 1: Extract the token data Add this near the top where you parse the statusline JSON input: bash Extract context window data context window=$ echo "$input" | jq -c '.context window // null' current usage=$ echo "$input" | jq -c '.context window.current usage // null' Calculate context percentage context pct="" if "$context window" = "null" ; then context window size=$ echo "$context window" | jq -r '.context window size // 0' if "$current usage" = "null" ; then input tokens=$ echo "$current usage" | jq -r '.input tokens // 0' cache creation=$ echo "$current usage" | jq -r '.cache creation input tokens // 0' cache read=$ echo "$current usage" | jq -r '.cache read input tokens // 0' total tokens=$ input tokens + cache creation + cache read if "$context window size" -gt 0 ; then context pct=$ total tokens 100 / context window size fi fi fi Step 2: Add the cache health indicator Add this where you build your status line segments: bash Cache Health Indicator Detects broken cache: cache read stuck at 0 while cache creation is high if "$current usage" = "null" && -n "$context pct" ; then STATE DIR="/tmp/claude-code-state" mkdir -p "$STATE DIR" CACHE HEALTH FILE="${STATE DIR}/${SESSION ID}-cache-health.json" Track consecutive zero-read checks if -f "$CACHE HEALTH FILE" ; then prev checks=$ jq -r '.checks // 0' "$CACHE HEALTH FILE" 2 /dev/null prev zero reads=$ jq -r '.zero reads // 0' "$CACHE HEALTH FILE" 2 /dev/null else prev checks=0 prev zero reads=0 fi new checks=$ prev checks + 1 if "$cache read" -eq 0 && "$cache creation" -gt 0 ; then new zero reads=$ prev zero reads + 1 else Reset on any successful cache read new zero reads=0 fi Persist state across refreshes printf '{"checks":%d,"zero reads":%d,"last read":%s,"last creation":%s,"timestamp":"%s"}\n' \ "$new checks" "$new zero reads" "$cache read" "$cache creation" \ "$ date -u +%Y-%m-%dT%H:%M:%SZ " "$CACHE HEALTH FILE" 2 /dev/null Skip first 2 checks cold start -- no cache exists yet, zero reads is normal After 3+ consecutive zero-read checks, warn about cache thrashing if "$new checks" -gt 2 && "$new zero reads" -ge 3 ; then status parts+= "${RED}CACHE MISS${RESET}" elif "$new checks" -gt 2 && "$cache read" -gt 0 ; then Show cache hit ratio when healthy cache total=$ cache read + cache creation if "$cache total" -gt 0 ; then cache hit pct=$ cache read 100 / cache total dollar='$' if "$cache hit pct" -gt 80 ; then status parts+= "${GREEN}${cache hit pct}%${dollar}${RESET}" elif "$cache hit pct" -gt 50 ; then status parts+= "${YELLOW}${cache hit pct}%${dollar}${RESET}" else status parts+= "${RED}${cache hit pct}%${dollar}${RESET}" fi fi fi fi What you'll see in the statusline - 92%$ in green -- healthy, 92% of tokens hitting cache saving money - 45%$ in red -- poor cache hit rate, you're overpaying - CACHE MISS in red -- cache is completely thrashed, zero reads for 3+ consecutive checks Why this matters A broken cache means you're paying full input token price every turn instead of getting the ~90% discount. It also increases latency. I found that certain workflows like batch tool calls in quick succession consistently thrash the cache, and was able to restructure them once I could actually see it happening in real time. SESSION ID should match however you identify your session -- tmux pane ID, env var, or a hash of the working directory.