Metadata-Version: 2.4
Name: amagi-cachelens
Version: 0.1.0
Summary: Shows where the Claude Code prompt cache missed, why, and what each miss cost
Author-email: "AmagiLabs (Amagisolutionsgroup, Inc.)" <dev@amagisolutionsgroup.com>
License: MIT
Keywords: claude-code,prompt-caching,cost,tokens,cli
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# 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](assets/demo.gif)

## Install

```bash
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:

```bash
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:

```bash
amagi-cachelens examples/demo-session.jsonl
```

```text
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:

```bash
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](https://github.com/amagilabs).

## License

MIT. Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs).
