overburn

ccusage tells you what you spent. Overburn tells you what you shouldn't have.

Overburn audits your local Claude Code session logs and reports how much of your spend was recoverable waste — with a named cause and a concrete fix for every dollar. It runs 100% on your machine, against logs that already exist on disk. No server, no account, no data ever leaves your computer.

npx overburn

  ◤ Overburn · audit of ~/.claude/projects · last 30 days

  You overburned an estimated $136 of $203 API-equivalent value.
  That's 67% of your usage you didn't need to spend.

  ▍Where it went
  ● Zombie context     $98   cacheRead beyond the 80k-token baseline
  ● Model mismatch     $37   Opus used for work Sonnet handles
  ● Redundant reads    $1    DatasetDetail.tsx read 21× in one session
  ○ Fat tool outputs   $0    no >50k-token tool dumps — healthy ✓
  ○ Failure loops      $0    tool error rate 4% — healthy ✓

  ▍Top fixes (est. $135/mo back)
  1. /clear between unrelated tasks
  2. Set the default model to Sonnet for routine work
  3. Read files once; rely on prior reads in context

What it does

Every other tool in the space is a meter — "how much did I use?" Overburn is the audit — "how much did I waste, why, and what do I change?" It looks for:

• Zombie context — requests dragging six-figure token counts a disciplined workflow wouldn't need.
• Model mismatch — premium-model calls doing work a cheaper model handles.
• Redundant reads — the same file read over and over in one session.
• Failure loops — repeated tool errors burning tokens.
• Fat tool outputs — giant command dumps that live in context forever.
• Session hygiene — marathon sessions that never got a /clear.

Overlapping causes are never double-counted: Overburn attributes each dollar of waste exactly once (see the joint attribution model in docs/PLAN.md).

Commands

| Command | What it does | | --- | --- | | overburn | The default terminal report (headline waste, findings, top fixes). | | overburn report | Writes a self-contained overburn-report.html and opens it — with the sawtooth context-growth chart, finding cards, and per-project/session tables. Works fully offline. | | overburn explain <id> | The math behind one detector, e.g. overburn explain zombie-context. | | overburn share | Writes a shareable overburn-share.svg card — scrubbed of paths and project names by default. | | overburn pricing [--refresh] | Show the active pricing table, or refresh it from the maintained copy. | | overburn --json | The full AuditReport as JSON, for scripting. |

JSON output

overburn --json prints a single AuditReport object — the same shape the HTML report is built from. Its schema is defined (and validated) as a zod schema in src/report.ts (auditReportSchema): top-level totals (spentUSD, wasteUSD, wastePct), a findings[] array (each with detector, severity, wasteUSD, attributedUSD, evidence, fix, perSession), an attribution block, framing, and coverage. Dollar amounts are exact (cents) in JSON; the terminal report rounds to whole dollars. See docs/PLAN.md §5.2 for the field-by-field contract.

Common flags

• --since 7d|30d|all — time window (default 30d).
• --project <substring> — only logs whose path contains this substring.
• --dir <path> — audit a specific file or directory instead of ~/.claude/projects.
• --no-ai — skip the optional AI narrative (see below).
• --no-open — for report/share, don't auto-open the written file.

The optional AI layer

When you run the interactive report and the claude CLI is on your PATH, Overburn can add a short natural-language read and up to three CLAUDE.md suggestions — produced by your own claude -p, so your subscription pays and there's zero server cost.

It is strictly additive and privacy-preserving: only a compact numeric digest (detector ids, severities, dollar amounts, totals) is ever sent to claude — never any log content, prompts, or file paths. Any failure (no claude, timeout, unparseable output) degrades silently to the deterministic report. Turn it off entirely with --no-ai.

Privacy

No telemetry. No account. The only network call Overburn ever makes is the opt-in overburn pricing --refresh (fetching the maintained pricing table from this repo). No log content is transmitted anywhere — the AI layer sends only the numeric digest described above, to a binary running on your own machine. Overburn never modifies your Claude Code settings or CLAUDE.md; it prints snippets, you apply them.

Install

Requires Node.js >= 18. Runs on macOS, Linux/WSL, and Windows (logs are read from ~/.claude/projects, or %USERPROFILE%\.claude\projects on Windows).

npx overburn          # no install — run the latest
# or
npm install -g overburn

Development

npm ci              # install dependencies
npm run typecheck   # type-check without emitting
npm test            # run the test suite (vitest)
npm run build       # compile to dist/

The full product spec lives in docs/PLAN.md.

License

MIT