amagi-cachelens
Reads your Claude Code session logs, shows which turns missed the prompt cache, names the likely cause, and prices each miss. Built for developers and small teams who watch their Claude Code bill or rate limit jump and can't tell why.
Install
pipx install amagi-cachelens
Or from source: pipx install git+https://github.com/amagilabs/amagi-cachelens.
Python 3.9+, no dependencies. Nothing leaves your machine: it only reads the .jsonl files Claude Code already wrote.
Use
Run it in a project directory and it reads that project's newest session:
amagi-cachelens
Or point it at any session file. This one is a synthetic log in the repo (examples/), built to hit every cause the tool knows:
amagi-cachelens examples/demo-session.jsonl
session: demo-session.jsonl
16 API calls, 6 cache misses, overall hit ratio 60%, models: opus-5-5, sonnet-5-5
estimated spend $0.82, of which misses wasted $0.44
# time gap read written missed cost wasted verdict
--------------------------------------------------------------------------
5 10:08:30 7.0m 0 21,000 20,903 $0.14 $0.12 MISS ttl_expired: gap 7.0m > 5m TTL
7 10:10:10 50s 9,000 13,800 12,903 $0.10 $0.07 MISS claude_md_changed: 'instructions' entry logged between turns (heuristic)
9 10:11:50 1.0m 6,000 17,500 17,503 $0.12 $0.10 MISS tool_list_changed: 'tools' entry logged between turns (heuristic)
11 10:13:20 50s 0 24,100 24,103 $0.09 $0.08 MISS model_switch: claude-opus-5-5 -> claude-sonnet-5-5
13 10:15:10 1.2m 0 9,000 9,003 $0.04 $0.03 MISS compaction: compact_boundary logged before this turn
15 10:16:50 1.0m 0 9,800 9,803 $0.04 $0.03 MISS unexplained: gap within TTL, same model, no change entry
Where the waste went:
ttl_expired 1 miss 20,903 tokens $0.12 idle gap longer than the cache TTL
tool_list_changed 1 miss 17,503 tokens $0.10 MCP or tool list changed
model_switch 1 miss 24,103 tokens $0.08 model changed, caches are per model
claude_md_changed 1 miss 12,903 tokens $0.07 CLAUDE.md / instructions were reloaded
unexplained 1 miss 9,803 tokens $0.03 full miss, no cause visible in the log
compaction 1 miss 9,003 tokens $0.03 conversation was compacted, new prefix
Dollar figures are estimates from a built-in price table (see --prices).
Causes are inferred from the log, not reported by the API.
More options:
amagi-cachelens --all examples/demo-session.jsonl # every turn, hits included
amagi-cachelens --json examples/demo-session.jsonl # machine-readable
amagi-cachelens --format md examples/demo-session.jsonl # paste into a PR or issue
amagi-cachelens --fail-over 5 examples/demo-session.jsonl # exit 1 if misses wasted more than 5 dollars
amagi-cachelens --prices my_prices.json examples/demo-session.jsonl
my_prices.json overrides the built-in table by model-name substring: {"opus": {"input": 5, "output": 25}} (dollars per million tokens).
How it decides
Every API call logs how many tokens were read from cache and how many were written. If call N-1 left a prefix in cache and call N didn't read it back, that gap is a miss. The tool then checks, in this order:
| Cause | Signal in the log |
|---|---|
compaction |
a compact_boundary entry before the turn |
model_switch |
the model id changed (caches are per model) |
ttl_expired |
the idle gap beat the TTL: 5 minutes, or 1 hour when the previous turn wrote to the 1-hour cache |
claude_md_changed |
an instructions reload entry between turns |
tool_list_changed |
an MCP or deferred-tool delta between turns |
hook_output_changed |
hook output was injected between turns |
listing_changed |
the skill or agent listing changed |
prefix_changed |
partial read: something early in the prompt changed |
unexplained |
full miss, none of the above visible |
The four signal-based causes (CLAUDE.md, tools, hooks, listing) are heuristics. They tell you what changed around the miss, not a guarantee of what broke the cache.
Dollar cost of a miss is the extra you paid for re-writing the tokens instead of reading them: write rate (1.25x input for 5-minute, 2x for 1-hour) minus read rate (0.1x input). Max-plan users can read the token counts as quota burn.
Limits
- Prices are a built-in estimate. The logs don't record what you were billed.
- Gaps are measured from log timestamps, so they're accurate to a few seconds.
- Subagent turns are skipped unless you pass
--sidechains. - Log formats change between Claude Code versions. Unreadable lines are skipped, never fatal. If a version breaks it, open an issue with a scrubbed sample.
Works with Claude Code as a skill
.claude/skills/amagi-cachelens/SKILL.md ships in the repo. Copy it to ~/.claude/skills/ and ask Claude "why did that session cost so much?"
If this saved you time
A star helps other people who are staring at the same bill find it.
More tools from the lab: github.com/amagilabs.
License
MIT. Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs).
Metadata
Release files for amagi-cachelens 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| amagi_cachelens-0.1.0.tar.gz | 15.6 kB | Without provenance | Details for amagi_cachelens-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| amagi_cachelens-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for amagi_cachelens-0.1.0-py3-none-any.whl |
Total release size: 28.9 kB
Release files / amagi_cachelens-0.1.0.tar.gz
| Download URL | amagi_cachelens-0.1.0.tar.gz |
|---|---|
| Size | 15.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
71681a731128b316fed05c57c34635f401ed3c90d4a5e590cc0eda95c90e411e
|
|
BLAKE2b-256 checksum How to use checksums |
56a9918880a3d95ee7e77e4cd6f5ceb36aa6fe1752ed76d6dcde87ab9d2b560e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / amagi_cachelens-0.1.0-py3-none-any.whl
| Download URL | amagi_cachelens-0.1.0-py3-none-any.whl |
|---|---|
| Size | 13.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8d03a018d8586418dc1828d2e0de8a1e627f6a7491e4912068ecbb9985a5c26e
|
|
BLAKE2b-256 checksum How to use checksums |
eb2e6bcf8f63e1ab8c087a14a90fc6bcaa0a23323196acf0601489089e31ae14
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for amagi-cachelens 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.