burndown 0.1.0

A local, real-time cockpit for your Claude credit burn — burn rate, runway forecast, and budget alerts. Zero dependencies, nothing leaves your machine.

Burndown

A local, real-time cockpit for your Claude credit burn. Burn rate · runway forecast · budget alerts — so you see "I'll run dry in 3 days" before it happens, not after.

---

Anthropic split programmatic Claude usage into a separate monthly credit pool that can run out mid-month. The existing tools show you what you already spent — a bank statement, after the fact. Burndown is the fuel gauge: how fast you're burning right now, when you'll hit zero, and a check that fires before you overspend.

It reads the usage logs Claude Code already writes on your machine. Nothing leaves your computer — zero dependencies, no network, read-only on your logs, and it never touches your prompts or code (see SECURITY.md).

Quickstart

pipx install git+https://github.com/aryasgit/burndown.git   # works today (PyPI: `pipx install burndown` — soon)
burndown                     # snapshot of this period
burndown budget 100          # set your monthly credit-pool budget → get a runway
burndown scope programmatic  # guardian mode: meter just the credit pool
burndown currency INR        # show INR next to USD (static rate, no live fetch)
burndown watch               # live terminal dashboard …
burndown serve               # … or a web dashboard at http://127.0.0.1:8787

No install? From a clone: python -m burndown (needs Python 3.11+, nothing else).

  BURNDOWN   monthly period · resets Jul 01

  $41.80 / $100.00   ███████████░░░░░░░░░░░░░░░░░  42%

  burn rate   $6.10/day   (last 24h)      avg $3.20/day
  runway      9.6 days  (Jun 22)   ✓ lasts the period
  projected   $89.40 by reset

  top projects
    memcon                     $22.10
    burndown                   $11.40
    barq-firmware              $8.30

  last 14d    ▂▁▃▅▂▇█▄▃▂▅▆▃▄

  1,204 billable msgs · 38,902,114 tokens · 100% local, nothing sent anywhere

Commands

Command	What it does
burndown / burndown status	one-shot snapshot
burndown watch [--interval 5]	live dashboard, re-reads logs every few seconds
burndown budget <amount> [--tokens] [--reset-day N]	set the budget runway is measured against (dollars, or --tokens to skip pricing)
burndown scope programmatic	guardian mode — meter just the June-2026 credit pool (programmatic usage); all / interactive also available
burndown currency INR [--rate R]	show a second currency next to USD (static rate, no live fetch)
burndown check	exit 0 ok · 1 projected-over · 2 over — wire it into your own pre-run hook / CI
burndown report [--html out.html]	self-contained local HTML report (opens from file://, no server)
burndown serve [--port 8787]	live web dashboard on 127.0.0.1 — local only, auto-refreshing (nice if you don't live in a terminal)
burndown config	show config + verify which logs are being read

How it works

Claude Code logs every assistant message to ~/.claude/projects/**/*.jsonl with a usage block (input / output / cache-write / cache-read tokens). Burndown reads those numbers (only those — never the message text), prices them with a configurable per-model table, rolls them into your current billing period, computes burn rate from the last 24 hours, and projects when you'll hit your budget.

Honest limitations

• Pricing is estimated and configurable. Default per-model rates are best-effort; correct them in ~/.config/burndown/config.toml (burndown config shows the active table). The burn-rate/runway math is exact regardless — prices only scale the dollar figure. Prefer not to trust a dollar estimate? burndown budget <N> --tokens forecasts in raw tokens.
• It reads local Claude Code logs. If your usage doesn't write those logs (e.g. a flow that doesn't log locally), Burndown can't see it yet.
• The "budget stop" is a check you act on, not an auto-kill (on purpose — see ADR-005).

Trust

Zero dependencies · no outbound network (the optional dashboard is loopback-only) · read-only · content-blind · cross-platform (macOS/Linux/Windows) · MIT. Verify it yourself in one line:

grep -REn "urllib|httpx|requests|telemetry|analytics|0\.0\.0\.0|socket\.socket|create_connection|\.connect\(" burndown/   # → nothing (the only socket binds 127.0.0.1)

Decisions are logged in docs/DECISIONS.md; the threat model is in docs/SECURITY.md.