burn-safe-token-ledger

Burn-Safe Token Ledger

Survive Anthropic's June 15, 2026 Agent SDK credit change with your bill unchanged.

A portable Claude Code skill that measures where your Claude tokens actually go, separates the spend that moved to the new metered credit from the spend that didn't, projects the cost impact for your specific plan from your own history, breaks out how much caching is saving you (and how much more it could), and turns all of that into concrete caching and routing fixes — then offers to implement them.

Credit: the token-burn dashboard concept is Nate B. Jones' (June 2026). This project's contribution is the caching-impact breakout — counting and attributing cache savings per system and per class — plus the interactive-vs-programmatic split that the June 15 change introduced. See CREDITS.md.

Why this exists

On June 15, 2026 Anthropic split subscription usage in two:

• Interactive Claude (you driving a Claude Code session, Cowork, web/desktop/mobile) → stays on your subscription limits, unchanged.
• Programmatic Claude (Agent SDK, claude -p, Claude Code GitHub Actions, third‑party SDK tools) → draws a separate monthly Agent SDK credit (Pro $20 / Max 5× $100 / Max 20× $200), metered at full API rates, with a hard stop when exhausted unless you enable extra usage.

The deciding signal is authentication, not task. Most people who lose money do it by habit — running headless work on the subscription that used to be free and is now metered. This tool finds that work and helps you move or cache it.

Install

As a marketplace plugin:

claude plugin marketplace add emergentcap/burn-safe-token-ledger
claude plugin install burn-safe-token-ledger@burn-safe-token-ledger

Or clone and point Claude Code at the skill directly:

git clone https://github.com/emergentcap/burn-safe-token-ledger

Quick start

cd skills/burn-safe-token-ledger
cp examples/personal-config.example.json personal-config.json   # edit paths + plan (gitignored)

python3 scripts/ingest_usage.py --config personal-config.json --out usage.normalized.jsonl
python3 scripts/classify_burn.py usage.normalized.jsonl
python3 scripts/estimate_credit_impact.py usage.normalized.jsonl --plan max20x
python3 scripts/analyze_caching.py usage.normalized.jsonl

Try it immediately against bundled sample data:

python3 scripts/classify_burn.py examples/sample-usage.jsonl

Or just ask Claude Code: "audit my Claude burn and tell me how June 15 affects my bill." The skill drives the whole flow. Re-run on a schedule with /loop 1d /burn-audit.

What you get

• classify_burn.py — interactive vs programmatic spend, attributed by system, with cache savings per bucket.
• estimate_credit_impact.py — projected monthly programmatic cost vs your plan's credit (low/expected/high).
• analyze_caching.py — cache hit rate, dollars saved, and dollars still recoverable, ranked by system.
• assets/credit-panel.html — a drop-in dashboard panel for the two figures that now matter.
• References — the billing policy, cost model, caching playbook, routing strategies, and workflow upgrades.
• examples/uplift-router.reference.py — a local-first model router with a daily spend cap that keeps heavy work off the metered credit.

Privacy

Your real paths, plan, and usage live in personal-config.json and usage.normalized.jsonl, both gitignored. The repo ships only generic examples. Never commit your usage data.

Accuracy

Prices and policy drift. skills/burn-safe-token-ledger/scripts/prices.py and the policy reference are the single sources of truth; the evals/ pin the math. See MAINTENANCE.md.

License

MIT — see LICENSE. Not affiliated with Anthropic. Verify current pricing and policy against Anthropic's official docs before making billing decisions.