---

name: cache-efficiency description: > Analyze prompt-cache effectiveness for Claude Code usage from the Agent Monitor dashboard — cache hit rate (total_cache_read / (total_cache_read + total_input)), cache_write vs cache_read reuse, cache-read vs cache-write spend, and the sessions with the poorest reuse. Pulls token totals from /api/analytics, per-session detail from /api/sessions, and dollar splits from /api/pricing/cost. Use when diagnosing cache spend or deciding whether prompt caching is paying off.

Cache Efficiency

Diagnose whether prompt caching is actually saving money, and where it is not.

Input

The user provides: $ARGUMENTS

This may be: empty (analyze the whole fleet), "today" / "this week" / a date range, a session ID to scope the analysis, or a target like "hit rate > 80%". When empty, analyze all data from /api/analytics.

Data Sources

| Endpoint | Returns | |----------|---------| | GET /api/analytics | tokens.total_input, tokens.total_output, tokens.total_cache_read, tokens.total_cache_write (baselines pre-summed), plus daily_sessions | | GET /api/sessions?limit=200 | Session list — each has model, cwd, started_at, ended_at, inline cost, metadata (JSON: usage_extras with cache token detail) | | GET /api/sessions/{id} | Full session detail with nested agents and events, for drill-down on a flagged session | | GET /api/pricing/cost | { total_cost, breakdown: [{ model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost, matched_rule }] } — used to price cache read vs write spend |

How cache economics work

cache_hit_rate   = total_cache_read / (total_cache_read + total_input)
cache_reuse      = total_cache_read / total_cache_write
cache_read_cost  = (cache_read_tokens  / 1M) × cache_read_per_mtok
cache_write_cost = (cache_write_tokens / 1M) × cache_write_per_mtok

Cache writes cost more per token than cache reads (e.g. Sonnet $3.75 write vs $0.30 read per Mtok), and writes are billed even if the cached block is never reused. The payoff only arrives on subsequent reads — so a healthy fleet shows cache_read_tokens far exceeding cache_write_tokens. When cache_reuse < 1, you are paying to cache context you barely re-read.

Token counts are effective totals = current + baseline (baselines preserve pre-compaction tokens).

Report Sections

1. Fleet Cache Hit Rate

From /api/analytics: compute cache_hit_rate × 100. State raw total_cache_read and total_input. Benchmark: >70% strong, 40–70% moderate, <40% weak prompt-cache utilization.

2. Write vs Read Reuse

Compute cache_reuse = total_cache_read / total_cache_write. Show both token counts. Flag if reuse < 1 (writing more cache than is ever read back).

3. Cache Spend Split

From /api/pricing/cost breakdown, sum cache_read_cost and cache_write_cost across all models. Show the dollar split and what fraction of total cost is cache-write overhead vs cache-read savings.

4. Sessions With Poor Reuse

From /api/sessions?limit=200, parse metadata.usage_extras for per-session cache read/write where available; rank sessions by lowest read/write reuse (and by cache_write-heavy cost). List the worst 10 with model, cost, and reuse ratio. Use /api/sessions/{id} to drill into any single flagged session.

5. Recommendations

• Sessions where cache_write >> cache_read: short or one-shot sessions rarely recoup cache writes — note them.
• Stable, repeated context (system prompts, large files) should be cached once and reused; high churn defeats caching.
• Estimate the dollar impact of raising the hit rate to the next benchmark tier.

Output

Structured Markdown with tables. Currency as USD to 4 decimal places; rates as $/Mtok; percentages with ▲/▼ for any trend. Token counts with thousands separators.