burn-safe-token-ledger

Burn-Safe Token Ledger

A portable workflow for surviving Anthropic's June 15, 2026 billing change with your bill unchanged. It 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, and turns that into concrete caching and routing fixes.

Token-burn dashboard concept credited to Nate B. Jones (June 2026). See CREDITS.md.

When to use this

Trigger on any of: "how does June 15 affect me", "Agent SDK credit", "programmatic vs interactive", "am I going to get a bill now", "reduce my Claude spend", "should I move to an API key", "make caching pay off", "smart model routing", "what's my burn".

The one rule the whole change hangs on

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

The deciding signal is authentication, not the task:

How the call authenticates	Where it bills after June 15
Your Claude subscription via OAuth, running the real Claude Code agent loop interactively	Subscription limits (no change)
ANTHROPIC_API_KEY / the Agent SDK / claude -p / Claude Code GitHub Actions	New Agent SDK credit, then API‑rate overage or hard stop
A third‑party API key (e.g. OpenRouter)	Already pay‑as‑you‑go — unaffected

Full policy detail and figures: references/billing-policy-2026-06-15.md.

Workflow (run in order)

0. Confirm scope and plan

Ask the user (or read personal-config.json): their plan (Pro / Max 5x / Max 20x / Team / Enterprise), whether "extra usage" is enabled, and the default model. These set the credit ceiling and per‑token prices. Never guess the plan — the credit ceiling depends on it.

1. Ingest their usage

Point the skill at their real usage sources. The canonical inputs are Claude Code session transcripts (~/.claude/projects/**/*.jsonl) for interactive burn, plus any logs from headless jobs (Agent SDK apps, claude -p scripts, GitHub Actions, cron/launchd jobs).

python3 scripts/ingest_usage.py --config personal-config.json --out usage.normalized.jsonl

ingest_usage.py reads each configured source, tags every turn with a class (interactive | programmatic) and a system label, and emits one normalized record per API turn. Sources and their classification live in personal-config.json — see examples/personal-config.example.json. If you cannot prove a source is interactive, default it to programmatic (fail safe toward the metered pool).

2. Classify the burn — what moved, and which systems generate it

python3 scripts/classify_burn.py usage.normalized.jsonl

Outputs total tokens and dollar cost split by class and by system, so you can see exactly how much of your spend just became metered and which automation is responsible. This is the attribution Nate's dashboard concept makes visible — extended here to the interactive vs programmatic axis that June 15 introduced.

3. Project the credit impact for their plan

python3 scripts/estimate_credit_impact.py usage.normalized.jsonl --plan max20x

Takes the programmatic slice, prices it at API rates for the configured model, projects to a full month, and compares against the plan's credit ceiling ($20 / $100 / $200). Reports: projected monthly programmatic cost, credit headroom or overage, and the break‑even number of runs. Always present this as a range (low/expected/high) anchored to their measured cache hit rate — see references/cost-model.md.

4. Find the caching wins

python3 scripts/analyze_caching.py usage.normalized.jsonl

Cache reads cost ~0.1× input price; a cache write costs ~1.25×. This script reports current cache hit rate, dollars already saved, and dollars still recoverable if stable prefixes were cached. Caching is now a direct dollar lever on the programmatic pool. Playbook: references/caching-playbook.md.

5. Recommend routing + workflow changes

Map findings to concrete moves (descriptions in references/routing-strategies.md and references/workflow-upgrades.md):

• Keep daily driving interactive (free under unchanged limits).
• Route heavy unattended work through a smart router with spend caps (local‑first → cheap cloud → Claude uplift) instead of claude -p on the subscription.
• Maximize prompt caching on whatever stays programmatic.
• Gate GitHub Actions behind labels / manual dispatch.
• Move production‑critical automation to a dedicated API key (no per‑user ceiling).
• Decide hard‑stop vs. overage before the cycle starts.

6. Offer to implement

Do not auto‑apply. Summarize the 3–5 highest‑value changes with their estimated monthly savings, then offer to implement each against the user's actual system (wire up the router, add cache breakpoints, add the credit panel to their dashboard, gate the Actions). Implement only what they accept.

Recurring use

This skill is built to be re‑run. Use the bundled /burn-audit command on an interval: /loop 1d /burn-audit re‑ingests, re‑classifies, and flags drift (e.g. a new cron job quietly eating the credit). See commands/burn-audit.md.

Personalization & privacy

All user‑specific paths, plan, and system labels live in personal-config.json, which is gitignored. The repo ships only examples/personal-config.example.json. Never commit a user's real paths, tool names, or usage data.

Keeping this skill accurate

Prices and policy change. Treat references/cost-model.md (prices) and references/billing-policy-2026-06-15.md (policy) as the single sources of truth, and run the evals/ cases after any edit. See MAINTENANCE.md.