cache-refund

KO | EN

gitlite — search

#nlp #rag #web #computer-vision #agent #reactjs #ai-agents #rust #kotlin #tailwindcss

(★ 9)

A cache doctor for Claude Code: find the money your prompt cache is leaking.

File Explorer

ZIP Download

- marketplace.json
- - bug.yml
  - config.yml
  - wrong-number.yml
- - ci.yml
  - release.yml
- PULL_REQUEST_TEMPLATE.md
- - organization-avatar.png
  - README.md
  - repository-open-graph.png
  - repository-open-graph.svg
- card-api.png
- card-subscription.svg
- card.svg
- - plugin.json
- account.ts
- actions.ts
- analyze.ts
- cardimage.ts
- cli.ts
- consent.ts
- costmodel.ts
- discover.ts
- format.ts
- keymenu.ts
- parse.ts
- pipeline.ts
- png.ts
- pricing.ts
- render.ts
- report.ts
- share.ts
- story.ts
- subagents.ts
- types.ts
- verdict.ts
- watch.ts
- - render.test.ts.snap
- - basic-5m.jsonl
  - compact.jsonl
  - dedup.jsonl
  - flat-fallback.jsonl
  - model-switch.jsonl
  - regime-1h.jsonl
  - sidechain.jsonl
  - summaries.ts
- - pty_run.py
- account.test.ts
- actions.test.ts
- analyze.test.ts
- cardimage.test.ts
- cli-flags.test.ts
- cli-help-version.test.ts
- cli-pty.test.ts
- cli-standalone.test.ts
- consent.test.ts
- discover.test.ts
- keymenu.test.ts
- oracle-parity.test.ts
- outcome.test.ts
- png.test.ts
- pricing.test.ts
- render.test.ts
- report.test.ts
- share.test.ts
- story.test.ts
- subagent-cli.test.ts
- subagents.test.ts
- verdict.test.ts
- watch.test.ts
- - analyze_cache_ttl.py
.gitignore
AUTHORS.md
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
GOOD-SETTINGS.md
LICENSE
METHODOLOGY.md
package-lock.json
package.json
README.md
SECURITY.md
tsconfig.json
vitest.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

CI Visit
npm Visit
node
dependencies
license

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Finds the money your Claude Code cache is leaking.**

![cache-refund API savings card](https://raw.githubusercontent.com/cache-refund/cache-refund/main/assets/card-api.png)

## How to run

### From a terminal

```bash
npx cache-refund
```

No install, no account, no config. Node 18+. (The installed command, once you
do install it, is plain `cache-refund`.)

### Inside Claude Code

```text
/plugin marketplace add cache-refund/cache-refund
/plugin install cache-refund@cache-refund
```

Then ask Claude Code to “run cache-refund” or “am I leaking money on cache?”
The plugin runs the analyzer and explains the result conversationally. It never
edits `settings.json` on your behalf; settings changes still go through the
CLI's own confirmation prompt.

If your npm configuration delays newly published packages, use the Claude Code
plugin instead.

> **100% local.** Reads token counts and timestamps only. No conversation content. No network.

Zero runtime dependencies, too — the entire tool is one `tsc`-compiled TypeScript
CLI, nothing to audit but the code itself.

- **API-billed, still on the 5-minute default?** The recommender leads with the
  projected monthly saving and asks once: "Switch to the 1-hour cache and save
  about $X/month? [Y/n]"
- **API-billed, already on the 1-hour TTL?** The validator: confirms 1h is still
  winning, or tells you to revert if your pattern shifted back toward 5m.
- **On a subscription?** The receipt: how much less of your usage limit the 1h
  cache uses than 5m, plus API-value context and the remaining quota leaks.

Below the break-even on any branch, you get **"Certified optimal"** instead of a
nag — that's also a screenshot worth sharing.

> In March 2026, the Claude API silently downgraded some 1-hour cache writes to
> 5-minute. Settings said 1h; transcripts billed 5m. `cache-refund` reads the TTL
> you *received*, never the one you set.

---

## How it works

Every cache-write is a token you paid a **markup** to store (1.25× base input on
the 5-minute TTL, 2× on the 1-hour TTL). `cache-refund` buckets each write by the
gap since the previous turn in that session. Then it prices a **symmetric
counterfactual** — what a fully-5m world and a fully-1h world would each have
billed on *your* tokens — so the verdict is a threshold you cross, not a guess.

| gap since previous turn | bucket | meaning |
|---|---|---|
| session start, or > 60 min | **cold** | unavoidable — a fresh cache had to be written. Informational. |
| 5–60 min | **recoverable** | the leak. A 1-hour TTL would still have this cached; a 5-minute TTL made you pay to write it again. |
| ≤ 5 min | **warm** | cheap re-use — cached under either TTL. |

The one number that decides the recommendation is **R/C** — the share of your
cache-write tokens that fell in the recoverable bucket. Above **39.5%**, the
1-hour TTL is cheaper for your pattern; below it, the 5-minute default already
wins. Not a vibe — it's `(2 − 1.25) / (2 − 0.1)`, derived in
[METHODOLOGY.md](./METHODOLOGY.md).

Run `npx cache-refund --explain` to see every formula with *your*
numbers substituted in.

## The fix, and how to trust it

For an API user whom the math tells to switch:

```bash
npx cache-refund enable     # adds ENABLE_PROMPT_CACHING_1H=1 to ~/.claude/settings.json
```

Settings changes still require confirmation (unless you pass `--yes`), back up
`settings.json`, and preserve every other key. The analyzer also saves one
content-free Markdown report per successful run under
`~/.claude/cache-refund/reports/`; reports contain aggregate counts, timestamps,
TTL evidence, calculations, and leak rows — never prompts or conversation text.
`npx cache-refund revert` undoes the settings change.

The env flag only applies to **sessions started after the change**, and Claude
Code has had intermittent flakiness landing it
([anthropics/claude-code#49139](https://github.com/anthropics/claude-code/issues/49139)),
so the tool verifies itself rather than asking you to trust it:

```bash
npx cache-refund verify     # after a few turns in a fresh session
```

`verify` re-reads your *newest* transcripts and checks the **TTL reality check**
— the TTL you are *actually receiving* per your last few days of usage, read
straight from the `ephemeral_5m`/`ephemeral_1h` usage fields, not from what
`settings.json` claims. If 1h landed, it says so. Later:

```bash
npx cache-refund recheck    # the comeback loop
```

`recheck` compares against a small baseline saved at enable time and shows
"since switching: $X saved". No external tools at any step — the product
verifies the product.

## Why the TTL reality check exists (a cautionary tale)

In March 2026 the Claude API server-side **silently downgraded** some 1-hour
cache writes to 5-minute for a stretch — settings said 1h, transcripts billed
5m. Anyone reasoning from their *config* rather than their *transcripts* was
quietly wrong for weeks.

The sharpest illustration we know of: a public community backtest once modeled
cache-keepalive strategies against an *assumed* TTL. When the models were
finally checked against real billed tokens, **six carefully-modeled strategies
all lost to a one-line heuristic** — and part of the modeling had rested on a
TTL that the server wasn't actually honoring. The lesson `cache-refund`
takes from that story: **measure the TTL you received, don't trust the one you set.**
That is why every checkup leads with the reality-check line, and why the
regression *watchdog* (below) is the roadmap's flagship.

## Share your card

```bash
npx cache-refund card
```

Post it with #cacherefund, or drop it in [the pinned Discussion](https://github.com/cache-refund/cache-refund/discussions/4).

## Other output modes

```bash
npx cache-refund share      # deal your card + the share prompt, any time
npx cache-refund card       # terminal receipt: outcome box, usage story, and share hint
npx cache-refund --md       # standard Markdown report for docs, issues, and Teams
npx cache-refund --slack    # Slack-native mrkdwn report, ready to paste
npx cache-refund --compact  # short outcome summary for logs and narrow terminals
npx cache-refund --json     # full machine-readable summary (stable schema, never prompts)
npx cache-refund --explain  # every formula, your numbers substituted (METHODOLOGY, one flag away)
```

Flags: `--days N` (default 90) · `--project <path>` (default: all projects) ·
`--price <model=$/MTok,...>` (override pricing) · `--yes` / `-y` (skip confirm) ·
`--no-color` · `--all-time` · `--no-share` (silence card generation and the final action menu; same as
env `CACHE_REFUND_NO_SHARE=1`) · `--plan <usd>` (monthly subscription price;
subscription branch only — overrides an automatically recognized plan price).
Exit codes: `0` ok · `1` no transcripts found · `2` parse/usage/internal error ·
`3` watchdog detected a TTL regression.

## FAQ

**I'm on a subscription (Pro/Max) — is there anything to do?**
Included subscription usage normally gets a one-hour TTL for the main
conversation. Subagents default to five minutes and can be configured separately,
including within your plan's included usage. Run `npx cache-refund subagents`
to inspect their actual cache writes and pauses. The subagent report does not
convert token counts into subscription quota savings. Dollar figures elsewhere are labeled
`$-equivalent (API list rates)` because the subscription quota formula is
undisclosed — we price your tokens at API list rates so the number is *anchored
and reproducible*, but it is not a bill. When Claude Code's local account cache
contains a recognized Max tier, `cache-refund` reads only the billing/tier fields
(never name, email, or account IDs) and shows the known plan framing. Unknown or
stale tiers stay price-free. `--plan <usd>` remains a manual override.

![cache-refund subscription receipt card](https://raw.githubusercontent.com/cache-refund/cache-refund/main/assets/card-subscription.svg)

**Does it work on Bedrock / Vertex?**
The analyzer reads the same transcript format regardless of provider. Cache TTL
availability depends on the provider and model. TTL settings also work on Claude
subscriptions; a configured flag or received TTL does not identify how a request
was paid for.

**Does it work with Codex / OpenAI?**
There's nothing for `cache-refund` to advise there. OpenAI's prompt caching is
automatic — writes cost nothing extra, cached reads are discounted, and
retention tiers are priced identically — so there's no 5m-vs-1h decision to
make. A cache-health view for other CLIs is on the roadmap.

**Is the efficiency score comparable between people?**
Only within a `score_version`. This is `score_version: 1` (printed in `--json`
and in [METHODOLOGY.md](./METHODOLOGY.md)). The formula is fully documented; if
it ever changes, the version bumps, so a v1 score is only ever compared to
another v1 score.

**A leak row says $0.00 — is that a bug?**
Almost certainly not. Subagent-5m overhead is $0 if you ran no sidechains in the
window; compaction rewrites are near-$0 if you rarely `/compact`; and the
recoverable-leak dollars are *net* of what a 1h TTL would itself cost, so a row
can legitimately be $0 when the tail write cancels the saving. Zero rows are
honest, not missing data.

**Does sharing phone home?**
No. The CLI itself makes zero network requests, sharing included. At the end of
an interactive run it generates the terminal-style card locally and shows one
single-key menu: Enter copies the image, `r` copies the detailed report, platform
keys open your own browser, `s` copies the Slack-formatted report, and `q`/Escape
exits. The saved card and report paths are shown above the menu. X and Bluesky receive prefilled
text through their compose URLs. LinkedIn opens its composer, copies the prepared
post text to your clipboard, and reveals the card image with its exact path for
attachment. Nothing is transmitted by `cache-refund`, ever. `--no-share` (or
`CACHE_REFUND_NO_SHARE=1`) suppresses the image/menu while the aggregate report
is still saved.

**I think a number is wrong.**
That is the highest-priority kind of bug report. Open a
[wrong-number issue](https://github.com/cache-refund/cache-refund/issues/new?template=wrong-number.yml)
— it asks for your `--json` and `--explain` output (token counts and timestamps
only, no content) so the exact figure can be reproduced and traced through the
formula.

## Inspect and configure subagent caching

```bash
npx cache-refund subagents             # child-only token and TTL report
npx cache-refund enable --subagents    # set subagentPromptCacheTtl to "1h"
npx cache-refund verify --subagents    # verify fresh child writes after the change
npx cache-refund revert --subagents    # explicitly set that setting to "5m"
```

Requires Claude Code **2.1.242+** for the scoped setting. It works during
**included subscription usage**, as well as API billing. Claude Code applies
`subagentPromptCacheTtl` to subagents and other requests outside the main
conversation, including helpers and workflows. These commands preserve the main
conversation's setting and any existing global TTL flag. Settings changes use
the CLI's confirmation and backup flow; `--yes` skips confirmation.
The existing unscoped `enable` command uses the legacy global flag, which can
affect both request groups where a higher-priority scoped control is absent.

The report separates explicit 5m writes, explicit 1h writes, and legacy writes
whose TTL is unknown. Mixed evidence stays mixed. Five-minute writes after
5–60-minute pauses are a reason to test a longer TTL, not a proven savings
amount. Short-lived agents may gain nothing, and a new subagent does not inherit
its parent's cache. **Subscription quota savings require separate measurement.**

`verify --subagents` checks only child writes in the last 24 hours and after the
last scoped change when available. Parent writes and older child writes cannot
certify success. It reports server-provided TTL counters; it does not test cache
retention over an hour or infer whether usage credits paid for a request.

The normal checkup and Markdown report include the child summary when present.
`--json` remains a read-only full Summary dump, including the additive
`subagents` field, even when combined with an action command. `watch` continues
to monitor the main conversation; `watch --subagents` and `recheck --subagents`
are not supported.

See [Claude Code's TTL controls](https://code.claude.com/docs/en/prompt-caching#choose-the-ttl-yourself).

## Watch for TTL regressions

```bash
npx cache-refund watch
```

Run this periodically (from cron, a scheduled task, or your shell). The first
run records the TTL your transcripts actually received. Later runs report the
current state and raise a clear, non-zero alarm if a working 1-hour TTL
falls back to 5 minutes. The watchdog stores only the observed TTL and check
time under `~/.claude/cache-refund/` — never prompts or conversation content.

## Roadmap

- Sleep-window learning to split cold gaps into "asleep" vs "abandoned".
- **v1.5 — `team`** aggregate mode (v1 already ships `--json` + a documented `jq`
  merge for fleets).
- **v2 — a policy simulator** behind the same cost model: price
  `5m+keepalive` and `1h+keepalive` for API users.

The roadmap has one rule (see [METHODOLOGY.md](./METHODOLOGY.md) and
[GOOD-SETTINGS.md](./GOOD-SETTINGS.md)): every new check must be *computed from
your transcripts, priced, and paired with one concrete fix.* Generic
settings-opinion tips are never product.

## Relationship to spend dashboards

Spend dashboards report what you **spent**. `cache-refund` reports what you
**wasted, why, and the fix** — it is the decision, not the dashboard. They
compose: watch your spend wherever you already watch it, then run `cache-refund`
when you want to know whether the cache defaults are costing you and what to
change. (The per-TTL write pricing here comes from Anthropic's published
per-model rates, re-derived in [METHODOLOGY.md](./METHODOLOGY.md) with the
retrieval date cited in `src/pricing.ts`.)

## Contributing & license

Wrong-number reports get a priority lane — see
[CONTRIBUTING.md](./CONTRIBUTING.md). MIT licensed.

An m8t labs project. See [AUTHORS.md](./AUTHORS.md) for core authorship and
contributor ownership details.

Methodology in full: [METHODOLOGY.md](./METHODOLOGY.md) · or run `npx cache-refund --explain`.

cache-refund

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README