kvleak 0.1.0__tar.gz

kvleak-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest -q
+      - run: kvleak breakeven 150k --no-color

kvleak-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,17 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing, no API token needed
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

kvleak-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+*.html
+!docs/**/*.html

kvleak-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2026-10-19)
+
+- First release: `audit`, `session`, `breakeven`, `statusline`, `pointer`, `models`.
+- Claude Code reader (incl. subagents, compaction markers, 5m/1h TTL breakdown) and generic JSONL reader
+  (Anthropic / OpenAI / Gemini / flat agent-framework usage keys).
+- Terminal, JSON, Markdown and self-contained HTML reports; `--fail-over` CI gate.

kvleak-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for helping! kvleak stays **zero-dependency** and **local-only**; please keep it that way.
+
+## Dev setup
+
+```bash
+git clone https://github.com/shangliy/kvleak && cd kvleak
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest -q && ruff check src tests
+python examples/make_demo.py demo && kvleak --path demo
+```
+
+## Adding a log format
+
+1. Write `read_<harness>(path) -> Transcript` in `src/kvleak/sources.py`. It must yield one
+   `Step` per *billed* model call, deduped, in chronological order.
+2. Teach `detect_format` to recognise it from the first few lines.
+3. Add a small fixture-based test in `tests/`.
+
+## Adding prices
+
+Add a `Price(...)` row to `BUILTIN` in `src/kvleak/pricing.py` and cite the provider's public
+pricing page in the PR. Keys match model ids by substring, and the longest match wins.
+
+## Good first issues
+
+- Readers for other agent CLIs (Codex CLI, Gemini CLI, Aider, OpenHands, Cline, ...)
+- A `--watch` mode that re-renders the audit every N seconds
+- Per-project rollups in the HTML report

kvleak-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kvleak contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kvleak-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: kvleak
+Version: 0.1.0
+Summary: Find where your AI coding agent leaks prompt-cache money (Claude Code, multi-agent, any JSONL) and how to stop it.
+Project-URL: Homepage, https://github.com/shangliy/kvleak
+Project-URL: Issues, https://github.com/shangliy/kvleak/issues
+Author: kvleak contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,cost,kv-cache,llm,multi-agent,observability,prompt-caching,tokens
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kvleak
+
+**Find out where your AI coding agent leaks prompt-cache money, and how to stop it.**  ·  [中文](README.zh-CN.md)
+
+[![CI](https://github.com/shangliy/kvleak/actions/workflows/ci.yml/badge.svg)](https://github.com/shangliy/kvleak/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/kvleak)](https://pypi.org/project/kvleak/)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+> **A 99.0% cache hit rate, and the session still leaked $82.** On Claude Fable 5.1 one
+> cache miss costs as much as 80 hits. In a 30-day audit of real Claude Code use, 2% of calls
+> carried more than half of all uncached input. [See the numbers →](docs/benchmarks.md)
+
+Your agent probably reports a 90%+ cache hit rate, and you are still overpaying.
+A cache miss costs about **12× more than a hit**, and the misses are rare but huge.
+They come from idle gaps that outlive the 5-minute TTL, from model switches, and
+from subagents that start cold. In real audits, **about 5% of calls burn about
+half of all uncached input**.
+
+`kvleak` reads the transcripts that are already on your disk, finds every
+expensive miss, says *why* it happened, and puts a dollar figure on it.
+
+```bash
+uvx kvleak          # or: pipx run kvleak  ·  pip install kvleak
+```
+
+No API key, no config, no network calls, no dependencies. It reads
+`~/.claude/projects` by default and any JSONL with token usage via `--path`.
+
+```text
+ kvleak · prompt-cache leak report
+ 14 sessions + 18 subagents · 1,594 model calls · 10.0k min miss size
+
+  Cache hit rate    92.1%  ██████████████████████
+  Input spend       $145.09   caching already saved you $791.64
+  Leaked to misses   $69.54   47.9% of input spend went to cache rebuilds and cold starts
+  Recoverable        $27.00   with break-even-capped keep-alive pings alone
+
+ Where the leak comes from
+  cause                            misses  uncached    leak  share
+  Idle gap outlived the cache TTL      48     10.0M  $38.40  55.2%  ████████▊
+  Model switched mid-session           21      5.2M  $18.34  26.4%  ████▏
+  Prefix changed within the TTL        16      2.6M  $11.14  16.0%  ██▌
+  New session cold start               14      336k   $1.61   2.3%  ▎
+  Subagent cold start                  18      468k  $0.054   0.1%
+
+ What to do about it
+  1. Idle gaps are your biggest leak class. Reply before the TTL ring empties, ...
+  2. Switching models throws away the whole cache (KV state is per model). ...
+```
+
+<sub>Output from the bundled synthetic demo: `python examples/make_demo.py demo && kvleak --path demo`</sub>
+
+---
+
+## Real numbers
+
+| | |
+|---|---|
+| 30 days of interactive Claude Code sessions | **97.5%** hit rate, but **27.5%** of input spend went to cache rebuilds |
+| Share of that leak caused by idle gaps | **82%** (median gap 2.8 h; Claude Code now uses the 1 h TTL) |
+| Cost of one miss on a 200k context | **$3.95** on Fable 5.1, $1.56 on Opus 5.5 (1 h TTL) |
+| 6-worker swarm, pointers + warm workers + pinned models | **−86%** input cost in simulation |
+
+Methodology and reproduction commands: [docs/benchmarks.md](docs/benchmarks.md).
+
+<p align="center"><img src="https://raw.githubusercontent.com/shangliy/kvleak/main/docs/assets/report.png" width="720" alt="kvleak HTML report"></p>
+
+## What you get
+
+| Command | What it does |
+|---|---|
+| `kvleak` | Audits every session: hit rate, dollars leaked, leak broken down by cause, leakiest sessions, worst single misses, and concrete next steps. |
+| `kvleak --since 7d --html report.html` | A self-contained HTML report (light/dark, no JS) you can share with your team. `--markdown` and `--json` also work. |
+| `kvleak session <id>` | Call-by-call timeline of one session, with each miss flagged and explained. |
+| `kvleak statusline --install` | Adds a live **cache TTL countdown** to Claude Code: `◕ cache 3:41 · 182k ctx · rebuild $0.89`. |
+| `kvleak breakeven 150k --idle 20m` | Tells you whether to keep this cache alive or let it die. |
+| `kvleak pointer build.log --status FAIL` | Turns a huge file into a ~60-token hand-off message for multi-agent boards. |
+| `kvleak --fail-over 15` | Exits with code 2 when more than 15% of input spend leaked, so it can gate CI or nightly jobs. |
+
+### Every miss gets a cause
+
+| Cause | What happened | Typical fix |
+|---|---|---|
+| **Idle gap outlived the TTL** | You were away for more than 5 min (or 1 h), so the next message rebuilt everything. | Watch the statusline countdown, batch work, or use capped keep-alive pings. |
+| **Prefix changed within the TTL** | Something near the top of the prompt changed: a timestamp, unsorted JSON, or a different tool list. | Make the prefix deterministic. |
+| **Model switched mid-session** | KV caches are per model, so a switch always means a full-price rebuild. | Pin one model per session or worker and hand off with pointers. |
+| **History compacted** | `/compact` or auto-compact rewrote the history. | Compact once at a natural break, not mid-task. |
+| **Cold start / subagent cold start** | A fresh agent paid full price for its system prompt and tool schemas. | Reuse warm workers; keep system prompts identical. |
+
+Only the **avoidable** part counts as leak: the context the cache already held,
+priced at write cost minus read cost. A new user message or new tool output
+would be paid for anyway, so it is not counted. Details:
+[docs/how-it-works.md](docs/how-it-works.md).
+
+## Live TTL countdown in Claude Code
+
+```bash
+kvleak statusline --install      # backs up settings.json; refuses to overwrite an existing statusLine without --force
+```
+
+```text
+◕ cache 3:41 · 182k ctx · rebuild $0.89        (green → yellow → red as the TTL drains)
+○ cache cold · next msg rebuilds 182k ($0.89)
+```
+
+When the ring is almost empty, sending your next message *now* refreshes the
+TTL at the cost of a cache read. If you already have a statusline script, call
+`kvleak statusline` from it; it reads the same JSON on stdin.
+
+## Should I keep this cache alive?
+
+```text
+$ kvleak breakeven 100k --model claude-sonnet-5 --idle 20m
+
+  Cached prefix 100k on claude-sonnet-5 (5m TTL)
+  Rebuild if it expires   125k tok-equiv  ($0.250)
+  ...of which avoidable   115k tok-equiv  ($0.230)
+  One keep-alive ping     10.0k tok-equiv  ($0.020)
+  Break-even              11 pings ≈ 54m30s of idle time
+
+  Idle 20m00s: 4 pings cost 40.0k tok-equiv  ($0.080), saving 75.0k tok-equiv  ($0.150). Keep it alive.
+```
+
+The rule is `K_max = floor((write − read) / read)`: 11 pings at 0.10× reads,
+24 at 0.05×, 49 at 0.025×. Past that, let the cache expire.
+
+## Running multi-agent swarms?
+
+Multi-agent and multi-model setups multiply leaks in three ways:
+
+* caches never cross models
+* shared boards make every agent re-read everyone's logs, which costs O(N²)
+* one-shot subagents each pay a cold-start tax
+
+**[The multi-agent cache playbook](docs/playbook.md)** describes six layers of
+practice: pinned models with pointer hand-offs, a script → small model → large
+model funnel, warm workers with TTL batching, a slim board contract,
+deterministic prefixes, and deliberate compaction. It includes a contract you
+can paste straight into your swarm's instructions, and `kvleak` measures each
+layer.
+
+```bash
+$ kvleak pointer /tmp/build.log --status FAIL --note "3 tests failing in //pkg"
+{"bytes":40211,"lines":512,"note":"3 tests failing in //pkg","path":"/tmp/build.log","sha256":"9f2c1e07a1b4c3d2","status":"FAIL","tail":[...]}
+```
+
+## Supported logs
+
+| Source | How |
+|---|---|
+| **Claude Code** (incl. subagents) | automatic: `~/.claude/projects`, respects `$CLAUDE_CONFIG_DIR` |
+| **Any JSONL with usage counters** | `--path <dir-or-file>`. Auto-detects Anthropic (`cache_read_input_tokens`), OpenAI (`prompt_tokens_details.cached_tokens`), Gemini (`cachedContentTokenCount`) and flat agent-framework keys (`input_tokens`, `cache_read_tokens`, `created_at`). |
+
+Prices for current Claude models are built in (`kvleak models`). For other
+providers, add a pricing file; see [`examples/pricing.json`](examples/pricing.json).
+Models without a price still get full token-level analysis.
+
+Want your agent harness supported natively? A reader is one small function
+that yields `Step`s. See `src/kvleak/sources.py` and [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Use it as a library
+
+```python
+from kvleak import analyze, load
+
+report = analyze([load("session.jsonl")])
+print(report.hit_rate, report.leak_usd, report.buckets["ttl_expiry"])
+```
+
+## FAQ
+
+**Is my data sent anywhere?** No. kvleak only reads local files and makes no
+network calls.
+
+**I'm on a subscription, not the API. Does this matter?** Yes. Cache misses
+use up your rate-limit headroom the same way they would cost money on the API.
+Read the dollar figures as relative weights.
+
+**My hit rate is 95%. Am I fine?** Maybe not. Hit rate counts tokens, not
+dollars, and one 800k-token rebuild weighs as much as thousands of cheap hits.
+Look at the *Leaked* line instead.
+
+**How accurate is the cause detection?** It follows the rules in
+[docs/how-it-works.md](docs/how-it-works.md). The main blind spot is very long
+generations: timestamps are written when a response ends, so a few TTL
+expiries can show up as prefix busts.
+
+## Credits
+
+Inspired by the cache-countdown idea in
+[olddonkey/cache-refresher](https://github.com/olddonkey/cache-refresher) and by
+production audits of multi-agent swarms.
+
+MIT licensed. Contributions welcome!

kvleak-0.1.0/README.md

@@ -0,0 +1,196 @@
+# kvleak
+
+**Find out where your AI coding agent leaks prompt-cache money, and how to stop it.**  ·  [中文](README.zh-CN.md)
+
+[![CI](https://github.com/shangliy/kvleak/actions/workflows/ci.yml/badge.svg)](https://github.com/shangliy/kvleak/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/kvleak)](https://pypi.org/project/kvleak/)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+> **A 99.0% cache hit rate, and the session still leaked $82.** On Claude Fable 5.1 one
+> cache miss costs as much as 80 hits. In a 30-day audit of real Claude Code use, 2% of calls
+> carried more than half of all uncached input. [See the numbers →](docs/benchmarks.md)
+
+Your agent probably reports a 90%+ cache hit rate, and you are still overpaying.
+A cache miss costs about **12× more than a hit**, and the misses are rare but huge.
+They come from idle gaps that outlive the 5-minute TTL, from model switches, and
+from subagents that start cold. In real audits, **about 5% of calls burn about
+half of all uncached input**.
+
+`kvleak` reads the transcripts that are already on your disk, finds every
+expensive miss, says *why* it happened, and puts a dollar figure on it.
+
+```bash
+uvx kvleak          # or: pipx run kvleak  ·  pip install kvleak
+```
+
+No API key, no config, no network calls, no dependencies. It reads
+`~/.claude/projects` by default and any JSONL with token usage via `--path`.
+
+```text
+ kvleak · prompt-cache leak report
+ 14 sessions + 18 subagents · 1,594 model calls · 10.0k min miss size
+
+  Cache hit rate    92.1%  ██████████████████████
+  Input spend       $145.09   caching already saved you $791.64
+  Leaked to misses   $69.54   47.9% of input spend went to cache rebuilds and cold starts
+  Recoverable        $27.00   with break-even-capped keep-alive pings alone
+
+ Where the leak comes from
+  cause                            misses  uncached    leak  share
+  Idle gap outlived the cache TTL      48     10.0M  $38.40  55.2%  ████████▊
+  Model switched mid-session           21      5.2M  $18.34  26.4%  ████▏
+  Prefix changed within the TTL        16      2.6M  $11.14  16.0%  ██▌
+  New session cold start               14      336k   $1.61   2.3%  ▎
+  Subagent cold start                  18      468k  $0.054   0.1%
+
+ What to do about it
+  1. Idle gaps are your biggest leak class. Reply before the TTL ring empties, ...
+  2. Switching models throws away the whole cache (KV state is per model). ...
+```
+
+<sub>Output from the bundled synthetic demo: `python examples/make_demo.py demo && kvleak --path demo`</sub>
+
+---
+
+## Real numbers
+
+| | |
+|---|---|
+| 30 days of interactive Claude Code sessions | **97.5%** hit rate, but **27.5%** of input spend went to cache rebuilds |
+| Share of that leak caused by idle gaps | **82%** (median gap 2.8 h; Claude Code now uses the 1 h TTL) |
+| Cost of one miss on a 200k context | **$3.95** on Fable 5.1, $1.56 on Opus 5.5 (1 h TTL) |
+| 6-worker swarm, pointers + warm workers + pinned models | **−86%** input cost in simulation |
+
+Methodology and reproduction commands: [docs/benchmarks.md](docs/benchmarks.md).
+
+<p align="center"><img src="https://raw.githubusercontent.com/shangliy/kvleak/main/docs/assets/report.png" width="720" alt="kvleak HTML report"></p>
+
+## What you get
+
+| Command | What it does |
+|---|---|
+| `kvleak` | Audits every session: hit rate, dollars leaked, leak broken down by cause, leakiest sessions, worst single misses, and concrete next steps. |
+| `kvleak --since 7d --html report.html` | A self-contained HTML report (light/dark, no JS) you can share with your team. `--markdown` and `--json` also work. |
+| `kvleak session <id>` | Call-by-call timeline of one session, with each miss flagged and explained. |
+| `kvleak statusline --install` | Adds a live **cache TTL countdown** to Claude Code: `◕ cache 3:41 · 182k ctx · rebuild $0.89`. |
+| `kvleak breakeven 150k --idle 20m` | Tells you whether to keep this cache alive or let it die. |
+| `kvleak pointer build.log --status FAIL` | Turns a huge file into a ~60-token hand-off message for multi-agent boards. |
+| `kvleak --fail-over 15` | Exits with code 2 when more than 15% of input spend leaked, so it can gate CI or nightly jobs. |
+
+### Every miss gets a cause
+
+| Cause | What happened | Typical fix |
+|---|---|---|
+| **Idle gap outlived the TTL** | You were away for more than 5 min (or 1 h), so the next message rebuilt everything. | Watch the statusline countdown, batch work, or use capped keep-alive pings. |
+| **Prefix changed within the TTL** | Something near the top of the prompt changed: a timestamp, unsorted JSON, or a different tool list. | Make the prefix deterministic. |
+| **Model switched mid-session** | KV caches are per model, so a switch always means a full-price rebuild. | Pin one model per session or worker and hand off with pointers. |
+| **History compacted** | `/compact` or auto-compact rewrote the history. | Compact once at a natural break, not mid-task. |
+| **Cold start / subagent cold start** | A fresh agent paid full price for its system prompt and tool schemas. | Reuse warm workers; keep system prompts identical. |
+
+Only the **avoidable** part counts as leak: the context the cache already held,
+priced at write cost minus read cost. A new user message or new tool output
+would be paid for anyway, so it is not counted. Details:
+[docs/how-it-works.md](docs/how-it-works.md).
+
+## Live TTL countdown in Claude Code
+
+```bash
+kvleak statusline --install      # backs up settings.json; refuses to overwrite an existing statusLine without --force
+```
+
+```text
+◕ cache 3:41 · 182k ctx · rebuild $0.89        (green → yellow → red as the TTL drains)
+○ cache cold · next msg rebuilds 182k ($0.89)
+```
+
+When the ring is almost empty, sending your next message *now* refreshes the
+TTL at the cost of a cache read. If you already have a statusline script, call
+`kvleak statusline` from it; it reads the same JSON on stdin.
+
+## Should I keep this cache alive?
+
+```text
+$ kvleak breakeven 100k --model claude-sonnet-5 --idle 20m
+
+  Cached prefix 100k on claude-sonnet-5 (5m TTL)
+  Rebuild if it expires   125k tok-equiv  ($0.250)
+  ...of which avoidable   115k tok-equiv  ($0.230)
+  One keep-alive ping     10.0k tok-equiv  ($0.020)
+  Break-even              11 pings ≈ 54m30s of idle time
+
+  Idle 20m00s: 4 pings cost 40.0k tok-equiv  ($0.080), saving 75.0k tok-equiv  ($0.150). Keep it alive.
+```
+
+The rule is `K_max = floor((write − read) / read)`: 11 pings at 0.10× reads,
+24 at 0.05×, 49 at 0.025×. Past that, let the cache expire.
+
+## Running multi-agent swarms?
+
+Multi-agent and multi-model setups multiply leaks in three ways:
+
+* caches never cross models
+* shared boards make every agent re-read everyone's logs, which costs O(N²)
+* one-shot subagents each pay a cold-start tax
+
+**[The multi-agent cache playbook](docs/playbook.md)** describes six layers of
+practice: pinned models with pointer hand-offs, a script → small model → large
+model funnel, warm workers with TTL batching, a slim board contract,
+deterministic prefixes, and deliberate compaction. It includes a contract you
+can paste straight into your swarm's instructions, and `kvleak` measures each
+layer.
+
+```bash
+$ kvleak pointer /tmp/build.log --status FAIL --note "3 tests failing in //pkg"
+{"bytes":40211,"lines":512,"note":"3 tests failing in //pkg","path":"/tmp/build.log","sha256":"9f2c1e07a1b4c3d2","status":"FAIL","tail":[...]}
+```
+
+## Supported logs
+
+| Source | How |
+|---|---|
+| **Claude Code** (incl. subagents) | automatic: `~/.claude/projects`, respects `$CLAUDE_CONFIG_DIR` |
+| **Any JSONL with usage counters** | `--path <dir-or-file>`. Auto-detects Anthropic (`cache_read_input_tokens`), OpenAI (`prompt_tokens_details.cached_tokens`), Gemini (`cachedContentTokenCount`) and flat agent-framework keys (`input_tokens`, `cache_read_tokens`, `created_at`). |
+
+Prices for current Claude models are built in (`kvleak models`). For other
+providers, add a pricing file; see [`examples/pricing.json`](examples/pricing.json).
+Models without a price still get full token-level analysis.
+
+Want your agent harness supported natively? A reader is one small function
+that yields `Step`s. See `src/kvleak/sources.py` and [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Use it as a library
+
+```python
+from kvleak import analyze, load
+
+report = analyze([load("session.jsonl")])
+print(report.hit_rate, report.leak_usd, report.buckets["ttl_expiry"])
+```
+
+## FAQ
+
+**Is my data sent anywhere?** No. kvleak only reads local files and makes no
+network calls.
+
+**I'm on a subscription, not the API. Does this matter?** Yes. Cache misses
+use up your rate-limit headroom the same way they would cost money on the API.
+Read the dollar figures as relative weights.
+
+**My hit rate is 95%. Am I fine?** Maybe not. Hit rate counts tokens, not
+dollars, and one 800k-token rebuild weighs as much as thousands of cheap hits.
+Look at the *Leaked* line instead.
+
+**How accurate is the cause detection?** It follows the rules in
+[docs/how-it-works.md](docs/how-it-works.md). The main blind spot is very long
+generations: timestamps are written when a response ends, so a few TTL
+expiries can show up as prefix busts.
+
+## Credits
+
+Inspired by the cache-countdown idea in
+[olddonkey/cache-refresher](https://github.com/olddonkey/cache-refresher) and by
+production audits of multi-agent swarms.
+
+MIT licensed. Contributions welcome!

kvleak-0.1.0/README.zh-CN.md

@@ -0,0 +1,50 @@
+# kvleak
+
+**找出你的 AI 编程 Agent 在 Prompt Cache 上漏掉了多少钱，以及怎么堵上。**  ·  [English](README.md)
+
+表面缓存命中率 90%+，账单却依然很贵？因为缓存**未命中比命中贵约 12 倍**，而且未命中虽然少、单次却很大：空闲超过 5 分钟 TTL、会话中途切模型、一次性子 Agent 冷启动……真实审计中，**约 5% 的调用吃掉了约一半的全价输入 Token**。
+
+> **缓存命中率 99.0% 的会话，照样漏了 82 美元。** 在 Claude Fable 5.1 上，一次缓存未命中的成本相当于 80 次命中。一份 30 天的真实 Claude Code 使用审计显示：2% 的调用占了一半以上的全价输入。[查看数据 →](docs/benchmarks.md)
+
+`kvleak` 直接读取本机已有的会话记录，找出每一次昂贵的缓存击穿，告诉你**为什么**发生，并折算成美元。
+
+```bash
+uvx kvleak          # 或：pipx run kvleak  ·  pip install kvleak
+```
+
+零依赖、零配置、不需要 API Key、不联网。默认读取 `~/.claude/projects`，其他带 token usage 的 JSONL 用 `--path` 指定。
+
+## 真实数据
+
+- 30 天交互式 Claude Code 会话：命中率 **97.5%**，但 **27.5%** 的输入花费用在了缓存重建上
+- 其中 **82%** 的漏损来自空闲间隔（中位数 2.8 小时；Claude Code 现在默认使用 1 小时 TTL）
+- 200k 上下文一次未命中的成本：Fable 5.1 上 **$3.95**，Opus 5.5 上 $1.56
+- 6 个 Worker 的 Swarm 模拟：指针交接 + 常驻 Worker + 锁定模型，输入成本 **−86%**
+
+## 功能
+
+| 命令 | 作用 |
+|---|---|
+| `kvleak` | 全量审计：命中率、漏损金额、按原因拆解、最漏的会话、最贵的单次未命中、可执行建议 |
+| `kvleak --since 7d --html report.html` | 生成可分享的自包含 HTML 报告（亦支持 `--markdown` / `--json`） |
+| `kvleak session <id>` | 单个会话逐步时间线，标出每一次未命中及原因 |
+| `kvleak statusline --install` | 在 Claude Code 状态栏显示**缓存 TTL 倒计时**：`◕ cache 3:41 · 182k ctx · rebuild $0.89` |
+| `kvleak breakeven 150k --idle 20m` | 保活还是放弃？按盈亏平衡点 `K_max = floor((write − read) / read)` 计算 |
+| `kvleak pointer build.log --status FAIL` | 把大文件变成约 60 Token 的「指针消息」，用于多 Agent 看板交接 |
+| `kvleak --fail-over 15` | 漏损超过输入花费的 15% 时以退出码 2 结束，可作为 CI 门禁 |
+
+## 未命中原因分类
+
+| 原因 | 含义 | 修复方向 |
+|---|---|---|
+| 空闲超过 TTL | 离开超过 5 分钟（或 1 小时），下一条消息全量重建 | 看倒计时及时回复、批量处理、按盈亏平衡点限制保活次数 |
+| TTL 内前缀变化 | 时间戳、未排序 JSON、工具列表变化导致前缀击穿 | 前缀确定性：`json.dumps(..., sort_keys=True)`、静态 System Prompt |
+| 会话中途切模型 | KV Cache 按模型物理隔离，切换必然全价重算 | 每个 Worker 锁定单一模型，跨模型用文件指针交接 |
+| 历史压缩 | `/compact` 或自动压缩重写历史 | 在自然断点主动压缩一次 |
+| 冷启动 / 子 Agent 冷启动 | 新 Agent 全价加载系统提示词与工具 Schema | 复用常驻 Worker，保持 System Prompt 完全一致 |
+
+## 多 Agent / 多模型
+
+[多 Agent 缓存手册（英文）](docs/playbook.md) 介绍六层优化：单 Worker 锁定模型并用指针交接、「脚本 → 小模型 → 大模型」算力漏斗、常驻 Worker 与 TTL 窗口批处理、公共看板瘦身契约（15 行以内）、确定性前缀、按水位线主动压缩。手册里附有一段可以直接粘贴进 Swarm 指令的契约。
+
+MIT 协议，欢迎贡献！

kvleak-0.1.0/docs/benchmarks.md

@@ -0,0 +1,85 @@
+# Numbers
+
+Three sets of numbers, each labelled by where it comes from. Re-run all of them
+yourself; every command is on this page.
+
+## 1. Case study: 30 days of one heavy Claude Code user
+
+The maintainer's own `~/.claude/projects`, from 2026-09-21 to 2026-10-20,
+audited with `kvleak`. Interactive sessions are those with 5 or more calls,
+plus their subagents. Headless one-shot `claude -p` runs are listed separately
+because they behave differently.
+
+| | interactive sessions | headless one-shot runs |
+|---|---:|---:|
+| transcripts | 289 (257 of them subagents) | 20,530 |
+| billed model calls | 13,110 | 20,592 |
+| cache hit rate (tokens) | **97.5%** | 59.4% |
+| input spend at list price | $1,522 | $468 |
+| what that input would cost with no caching | $18,085 | $548 |
+| **leaked to cache rebuilds** | **$418 (27.5% of input spend)** | $65 (13.8%) |
+| heavy misses as a share of calls | **2.2%** | 4.4% |
+| uncached input inside those misses | **53.7%** | 11.0% |
+
+Where the interactive leak came from:
+
+| cause | misses | leak | share |
+|---|---:|---:|---:|
+| Idle gap outlived the cache TTL | 124 | $345 | **82.4%** |
+| Subagent cold start | 127 | $27 | 6.5% |
+| Prefix changed within the TTL | 17 | $20 | 4.8% |
+| Model switched mid-session | 7 | $20 | 4.7% |
+| History compacted | 8 | $4 | 0.9% |
+| New session cold start | 4 | $3 | 0.7% |
+
+Takeaways:
+
+* **A high hit rate hides the leak.** The leakiest session had a **99.0%**
+  token hit rate and still leaked **$82**, because one rebuild of 800k tokens
+  outweighs thousands of cheap hits.
+* **About 2% of calls carry more than half of all uncached input.**
+* **Claude Code now writes about 90% of its cache with the 1-hour TTL**, so the
+  5-minute expiry is no longer the problem. The leak is the lunch, meeting and
+  overnight gaps: the median idle gap before a TTL miss was 2.8 h. 45 of the
+  124 expiries were under 2 h and worth bridging with a keep-alive, which would
+  have recovered **$90**.
+* Cold starts dominate headless runs, but each one is small. They're cheap
+  per call and only add up at volume.
+
+Reproduce on your own machine: `kvleak --since 30d`.
+
+> This is one person's usage, at list API prices. Your mix will differ, and
+> that's the point of running it yourself.
+
+## 2. What one cache miss costs, by model
+
+Avoidable cost of rebuilding a **200k-token** context instead of reading it
+(`(write − read) × 200k`), at list prices. Source: `kvleak models` and
+`kvleak breakeven 200k --model <m> --ttl <ttl>`.
+
+| model | one cache hit | one miss, 5-min TTL | one miss, 1-hour TTL | miss ÷ hit (1h) | keep-alive break-even (5m / 1h) |
+|---|---:|---:|---:|---:|---:|
+| Claude Fable 5.1 | $0.05 | $2.45 | **$3.95** | **80×** | 49 / 79 pings |
+| Claude Opus 5.5 | $0.04 | $0.96 | $1.56 | 40× | 24 / 39 pings |
+| Claude Sonnet 5.5 | $0.04 | $0.46 | $0.76 | 20× | 11 / 19 pings |
+| Claude Haiku 5.5 | $0.002 | $0.02 | $0.04 | 20× | 11 / 19 pings |
+
+Newer models make cache reads cheaper, so each miss hurts *more* relative to a
+hit. On Fable 5.1, a single miss costs as much as 80 hits.
+
+## 3. Simulation: a 6-worker swarm, 40 rounds
+
+`python examples/swarm_sim.py`. This is a transparent toy model, not a
+measurement. Every worker re-reads its context each round, and one failing
+build log (~8k tokens) is produced per round. Prices are Opus 5.5 with a
+5-minute TTL.
+
+| scenario | input (tok-equiv) | cost | vs naive |
+|---|---:|---:|---:|
+| naive: paste logs on the board, respawn the fixer, reviewer on another model | 17.8M | $71.10 | — |
+| + post pointers instead of logs (`kvleak pointer`) | 6.8M | $27.37 | **−62%** |
+| + keep the fixer warm instead of respawning | 5.8M | $23.18 | −67% |
+| + one model per worker (the [playbook](playbook.md)) | 2.4M | $9.63 | **−86%** |
+
+The board change alone removes most of the O(N²) broadcast cost, because one
+pasted log is re-read by every worker on every later turn.