kvleak

Your Claude Code cache hit rate is 95%+. A quarter of your input spend still goes to cache rebuilds. kvleak shows where, and fixes most of it with one command. · 中文

uvx kvleak            # or: pipx run kvleak  ·  pip install kvleak

No API key, no config, no network calls, no dependencies. It reads the session files Claude Code, Codex CLI, Gemini CLI and OpenCode already keep on disk and is done in seconds. On a subscription the dollars are list-price equivalents; the percentages are your rate-limit headroom.

 kvleak · prompt-cache leak report
 101 sessions + 276 subagents + 22,100 one-shot runs (Claude Code 81, Codex CLI 20) · 58,208 model calls

  Cache hit rate    95.4%  ██████████████████████▉
  Input spend        $2,602   caching already saved you $21,281
  Output spend      $452.39   replies + thinking at the output price · whole bill $3,054: 43.8% cache writes, 38.8% cache reads, 14.8% output
  Leaked to misses  $537.72   20.7% of input spend went to cache rebuilds and cold starts · 17.6% of the whole bill
  Dead writes       $215.71   write premium on tokens never read back (mostly one-shot `claude -p` runs)

 Where the leak comes from
  cause                            misses  uncached     leak  share
  Idle gap outlived the cache TTL     164     41.3M  $371.92  69.2%  ███████████
  New session cold start            1,378     36.3M   $81.67  15.2%  ██▍
  Subagent cold start                 145      4.1M   $29.44   5.5%  ▉

_{The maintainer's last 30 days. Yours will differ; that is the point. Post yours in #1.}

Turn it on

The audit changes nothing. These four do, each with an undo, and each takes effect in Claude Code sessions started afterwards:

pip install kvleak
kvleak tune --apply          # settings.json: compaction window, cache TTLs, idle compaction, Bash cap   (--reset)
kvleak hooks --install       # long shell output stays out of the context; compaction keeps an archive  (--uninstall)
kvleak refine --apply        # context-hygiene rules, with their dollar figures, in ~/.claude/CLAUDE.md (--remove)
kvleak statusline --install  # cache countdown in the status bar, ticking while you read              (--uninstall)

How to tell it worked: /hooks in Claude Code lists four kvleak entries, the status bar reads ● cache 59:47 · 86k ctx · rebuild $1.73 after the first reply, and a long seq 1 20000 comes back as head + tail + a path instead of 20,000 lines. A week later, kvleak probe puts a number on it.

Why the hit rate lies

A cache hit costs 0.1× the input price (0.025× on Fable 5.1). A rebuild costs 1.25–2×. One miss on a 200k context is worth 80 hits, so 2% of calls can carry half of all uncached input and the hit rate never moves. kvleak prices only the avoidable part of each miss: context the cache already held, at write price minus read price.

Why "60–90% fewer tokens" did not shrink your bill

Tool-output compressors shrink what the context carries, and carrying is paid at the cache-read price, the cheapest line on the bill. On 2,848 billed Claude Code runs, a 38% cut in tool output raised cost by 6.8% (arXiv 2607.12161). kvleak whatif replays each tool's promise on your own bill, as an upper bound:

$ kvleak whatif

  What if · 58,199 model calls · $3,053 over the last 30d
  Bill = $80.38 uncached input + $1,337 cache writes + $1,183 cache reads + $452.12 output

  if you…                who promises it                                     bill saving  share of bill
  kvleak tune --apply    compaction window, TTLs, idle compaction, Bash cap  −$786.56             25.8%
  Shell output −60%      rtk's low end ("60–90%")                            −$222.00              7.3%
  All tool results −40%  AgentDiet, arXiv 2509.23586                         −$183.98              6.0%
  Thinking −25%          effort high → medium                                −$59.22               1.9%
  Startup context −50%   claude-token-optimizer                              −$43.19               1.4%
  Replies half as long   caveman                                             −$32.74               1.1%

Compaction changes how much is carried at all. That is why the settings levers are three times the best compressor, on a history where 44% of the bill is cache writes.

Three commands

1. See the leak. kvleak (above). --since 7d, --html report.html for a shareable report, kvleak session <id> for one session call by call.

2. Fix the settings. Claude Code can compact for you, pick the cache TTL and compact idle sessions, but its defaults are tuned for nobody. kvleak tune replays your last 30 days under every value of each setting and --apply writes the winners to settings.json (backed up; --reset undoes it):

$ kvleak tune

  setting                                         now           best   saving / 30d  why
  autoCompactWindow                               auto (~967k)  200k        $720.52  98 compactions instead of 32 · −57.7% of input spend
  `claude -p` runs: CLAUDE_CODE_PROMPT_CACHE_TTL  1h            5m          $169.11  42% of their cache writes were never read back
  CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS             200k          100k         $19.72  153 idle gaps ≥54 min
  bashOutputMaxChars                              30,000        8,000        $32.54  Bash results are 29% of what entered the context

  Total if applied: $909 per 30d (−45% of input spend)
  Write these to ~/.claude/settings.json: kvleak tune --apply

A week later, kvleak probe shows what actually changed: input spend per call, leak share, context per call, compactions and shell output on your own interactive sessions before vs after the day you applied, and what the difference is worth per 30 days. Measured on what was billed, not replayed.

3. Watch the cache live. kvleak statusline --install puts a TTL countdown in Claude Code and tells you when carrying the context costs more than shrinking it:

◕ cache 3:41 · 182k ctx · rebuild $0.89
● cache 59:47 · 249k ctx · rebuild $1.99 · ⚠ /compact saves ~$9.42
◔ cache 1:19 · 250k ctx · rebuild $2.00 · ⚑ ≤2 pings pay

What else is in the box

Each of these is measured on your own history before it suggests anything. Numbers are the maintainer's 30 days; method and reproduction in docs/benchmarks.md.

audit, advise, keepalive and whatif read Claude Code, Codex CLI (~/.codex/sessions), Gemini CLI (~/.gemini/tmp/*/chats) and OpenCode (opencode.db) automatically. The context-level commands (diet, tune, hooks, refine) need the tool results themselves and read Claude Code only.

Full tour with outputs: docs/guide.md. How every number is computed: docs/how-it-works.md.

FAQ

Is my data sent anywhere? No. Local files only, no network calls.

I'm on a subscription. Misses eat the same rate-limit headroom they would cost in dollars on the API. Read the figures as relative weights.

Does trimming context hurt the model? In the A/B benchmark (bench/, 72 runs on Opus 5.5) every arm scored 1.0 on every task. The settings tune writes only compact above 200k context; --min-window raises that.

Credits

The countdown idea comes from olddonkey/cache-refresher; hooks, recall and refine borrow from Prime Agent and Harness². MIT licensed.