Install

Know your runway
before you hit
zero.

burndown — credit pool

$ burndown monthly · resets Jul 01 · scope: programmatic $8.66 / $100.00 ██░░░░░░░░░░░░░░░░░░░░░░░░ 9% programmatic $8.66 (credit pool) interactive $7,064.61 (≈ value at API rates) burn rate $0.71/day (last 24h) runway 128.1 days (Oct 19) ✓ lasts the period projected $21.39 by reset last 14d ▁▂▁▁█▁▁▁▁▂▁▁▁▁ 75 msgs · 1,979,456 tokens · 100% local, nothing sent

What it does Reads the usage logs Claude Code already writes. Turns the token counts into a burn rate, a runway forecast — “dry in N days” — and an over-budget check. Token counts only, never your message text. 100% local. Why now On Jun 15, 2026 Anthropic split programmatic Claude usage into its own monthly credit pool that can run dry mid-month, on its own. burndown is the gauge for it — and for your interactive usage too.

Start

One-line install →

Read the source →

Audit it in one grep ↓

burndown — a fuel gauge, not a bank statement

A small command-line tool that lives next to Claude on your laptop. It reads the usage logs Claude Code already writes, prices the tokens with a table you control, and tells you the rate you're burning at and the day you run dry. It meters local Claude Code usage — if a flow doesn't write those logs, burndown can't see it.

Existing tools show what you already spent, after the fact. This one shows the rate and the runway before you hit zero. Nothing leaves the machine. Zero runtime dependencies, read-only on your logs, content-blind by design. MIT.

Local-only · 00:00:00

Reads ~/.claude logs · sends nothing · MIT

Live · v0.1
CLI + opt-in 127.0.0.1 dashboard

The burn loop

From the logs Claude already writes to a runway you can act on — read-only, content-blind, every step on your machine.

Claude Codewrites logs

Logs every assistant message it sends.

~/.claude/projects/**/*.jsonl

Every assistant message lands in a JSONL line with a usage block — input, output, cache-write and cache-read token counts, plus the model and entrypoint. Claude Code writes these whether or not burndown is installed; burndown never asks it to log anything extra.

burndownread-only

Reads the token counts. Never the text.

content-blind

It opens those files read-only and reads only the token counts and metadata — model, timestamp, entrypoint. It never reads the message body. And it only sees these logs: if a flow doesn't write to ~/.claude, burndown can't see it — it meters local Claude Code usage, not everything.

burndownclassifies

Splits each event programmatic vs interactive.

scope=programmatic

Each event is tagged by its entrypoint — SDK / headless / CI runs are programmatic, your editor and desktop sessions are interactive. burndown scope programmatic meters just the Jun-2026 credit pool that can run dry on its own.

burndownprices

Prices the tokens with a table you control.

per-model · estimated

A configurable per-model rate table turns token counts into a dollar figure and rolls them into the current billing period. Prices are estimated — they only scale the dollar figure; the burn-rate and runway math underneath is exact. Prefer not to trust a price? Run with --tokens and forecast in raw tokens instead.

burndownprojects

Burn rate from 24h → a runway date.

runway 128.1d → Oct 19

Burn rate is computed from the last 24 hours — not a lifetime average — and projected against your remaining budget: a number of days and the actual date. “✓ lasts the period” or “runs dry before reset.” The whole point is to see the rate before the pool is empty.

Youthe check

Read it, watch it, or check it in CI.

exit 0 / 1 / 2

Glance at burndown, leave watch open in a pane, or wire burndown check into your own hook — it exits 0 (ok), 1 (projected over), or 2 (already over). It's a signal you act on; it never blocks or cancels a run.

What you get

A rate and a runway. Read before you hit zero, not a receipt after.

24^h

Burn rate from the last 24 hours. Not a lifetime average — the gauge tracks how hard you're going now, projected to a runway date.

0^deps

Pure Python stdlib. No packages to vet, nothing to pull from a registry — nothing to audit but the source. Python 3.11+ and you're done.

0^network

No outbound network. Read-only and content-blind — token counts only, never your prompts. The only socket is the optional 127.0.0.1 dashboard. Nothing leaves your computer.

~70^×

Value received, measured on one machine. ~$7,000 of API-equivalent value from a $100 plan ≈ 70× the plan price. burndown measures what you got — not what you owe.

The commands

Nine commands to read the burn, watch it live, and check it in CI.

In the browser

Don't live in a terminal?
Run serve and watch the gauge in a tab, on loopback.

●127.0.0.1:8787

burndown · monthly · scope programmatic live

$8.66 / $100.00 · 9% used

burn $0.71/day · last 24hprojected $21.39

Runway

128 days

Resets

Oct 19

Top project

memcon

serve

One command, local only

burndown serve opens an auto-refreshing dashboard at http://127.0.0.1:8787. Same numbers as the terminal — spend, burn rate, runway, top projects — laid out to read at a glance, for people who run Claude through the desktop app.

:8787

Loopback only

Bound to 127.0.0.1, never 0.0.0.0. It's a local UI, not a network service — nothing on your network or the internet can reach it. This is the only socket burndown ever opens; everything else is read-and-print.

file://

Or no server at all

Prefer not to open a socket? burndown report writes a self-contained HTML file you open from file:// — no server, no fonts or CDN, no telemetry, nothing fetched. The file holds aggregate numbers only — no conversation content — and is git-ignored by default.

Trust, verified

It watches your spend.
It earns its place on your machine.

A spend tool you don't have to take on faith.

Most "free" tools earn their keep with telemetry. burndown earns yours by having nothing to hide: it's small, it's pure-stdlib, and the whole thing reads in one sitting. Verify every claim below from the source — in one line.

✓Zero runtime dependencies.Pure Python standard library. No third-party packages, nothing pulled from a registry — nothing to audit but the source.
✓No outbound network.It makes no HTTP calls and opens no outbound connections. The only socket is the optional serve dashboard, bound to 127.0.0.1.
✓Read-only on your logs.It opens log files for reading and never writes to them. Re-runs change nothing on disk.
✓Content-blind.It reads token counts and metadata only — never the message body. It can't leak your prompts or code because it never reads them.

Audit it yourself

ResultNothing — the only socket binds 127.0.0.1. The whole tool is auditable in one read.

Threat modeldocs/SECURITY.md · ADRs

Install

One line. Nothing to vet.

Install, run, and see your first readout — no config.

Install with pipx straight from the repo and you get the burndown command on your PATH. Pure-Python stdlib, so there's nothing else to pull in. Run burndown and it reads the logs Claude Code is already keeping — set a budget with burndown budget 100 to get a runway. It's on PyPI, so the same one line works on macOS, Linux, and Windows.

Python 3.11+ · macOS, Linux, Windows · zero runtime dependencies
Read-only on your logs · content-blind · re-runs change nothing
From a clone, no install: python -m burndown

$ pipx install burndown

No installFrom a clone: python -m burndown — needs Python 3.11+, nothing else.

Dev buildBleeding edge from source: pipx install git+https://github.com/aryasgit/burndown.git.

$ pipx install burndown

Works onUbuntu · Debian · Fedora · Arch · WSL2. Python 3.11–3.13, 3-OS CI.

Sourcegithub.com/aryasgit/burndown — read it before you run it.

PS> pipx install burndown

PowerShellSame command. Or from a clone: python -m burndown.

Alsopip install burndown works too.