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.)
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.
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.
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.
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.--rates-file with 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.