Stop finding out you're rate-limited mid-task. Check the headroom first.
One sentence from a Show HN thread stuck with me: "Thing I'd want surfaced is per account rate limit headroom before I dispatch, not after I'm stuck mid task."
blackbox-bill v0.3.0 does exactly that. It was a post-mortem tool — it read your AI coding bill and explained why it looked wrong. Now it's also a pre-flight tool: it shows per-account quota headroom before you dispatch the next task, and tells you which account can survive it.
pip install blackbox-bill Zero dependencies — Python 3.9+ stdlib only. No network, no API keys; everything runs on files you already have. (GitHub, MIT.)
The dashboard
Billing exports never carry quota limits — no vendor puts remaining quota in a CSV — so you declare them once in a small JSON file. blackbox-bill subtracts your observed usage from your declared caps, per account, per quota pool:
blackbox-bill headroom --csv export.csv --limits-file limits.json account 'cursor-pro' (plan cursor:pro, 3 bill row(s)) pool consumed limit remaining remaining status api-key $0.00 unlimited unlimited [????????????????????] n/a UNLIMITED cursor-models $30.00 $500.00 $470.00 [###################-] 94.0% OK other-models $120.00 $125.00 $5.00 [#-------------------] 4.0% LOW Pools get flagged OK / LOW (under 25% left) / EXHAUSTED / UNLIMITED. limits.json looks like this — caps in USD, null for unlimited, and an optional match spec to partition bill rows across accounts by a CSV column value:
{ "accounts": [ {"name": "cursor-pro", "plan": "cursor:pro", "limits": {"cursor-models": 500.0, "other-models": 125.0, "api-key": null}}, {"name": "shared-api-key", "plan": "api-only", "limits": {"api-key": 200.0}, "match": {"column": "account", "value": "shared-api-key"}} ] } No CSV yet this cycle? Run it limits-only — the dashboard shows your declared caps and you re-run with the export later.
The dispatch simulator: which account survives this task?
Planning a long agent run? Add --task-in/--task-out and blackbox-bill re-prices the task under each account's plan rate card (the same illustrative cards the plan-switch what-if simulator uses) and recommends the account with headroom for it:
blackbox-bill headroom --csv export.csv --limits-file limits.json \ --task-in 1000000 --task-out 250000 --task-pool other-models 'cursor-pro' est $10.00 DOES NOT FIT (remaining $-5.00) 'shared-api-key' cannot price: no declared limit for pool 'other-models' WARNING: no account has headroom for this task under the declared limits. Top up, switch plan, or shrink the task before you dispatch — not after you're stuck mid task. Or, when an account does fit: RECOMMEND: dispatch on 'acct-b' — it has headroom for this task. Bring your own numbers with --rates-file and the estimates become real.
From post-mortem to pre-flight
v0.1–v0.2 were post-mortem: the bill arrived, the tool reconstructed why it looks wrong ("why your 'Other Models' pool drained first", silent model swaps, unattended $40-while-you-slept burn). v0.3 is pre-flight: remaining quota per account, and which account survives the next dispatch, before you commit.
The positioning doesn't change — it's still the same read-only billing-attribution ledger. No enforcement, no budget lines, no blocking. Use the statusline to watch the burn; use blackbox-bill to audit it — now also before you light the fuse.
Honest limitations
- Limits are self-declared. The dashboard is exactly as right as your
limits.json. If your plan cap changes and you don't update the file, the dashboard is wrong in the way you'd expect — keep the numbers conservative. - The simulator prices, it doesn't predict. Flat per-token rates; real overage behavior and request-based floors aren't modeled. "Fits" means "has budget for this size", not a guarantee.
- Rate cards are illustrative unless you pass
--rates-filewith your own.
The repo is hahahahahahahahah6/blackbox-bill (MIT). If you've ever been rate-limited mid-task with a quota sitting untouched on another account, this one's for you.
