Skip to main content

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.

amagi-cachelens demo

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)

Source distribution for amagi-cachelens 0.1.0
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)

Table of built distributions (wheels) for amagi-cachelens 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page