# Stop finding out you're rate-limited mid-task. Check the headroom first.

> Source: <https://dev.to/haoli/stop-finding-out-youre-rate-limited-mid-task-check-the-headroom-first-10ak>
> Published: 2026-10-17 07:55:06+00:00

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](https://github.com/hahahahahahahahah6/blackbox-bill), 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](https://github.com/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.