DEV Community

hao li
hao li

Posted on

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

#opensource #python #showdev

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
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
Enter fullscreen mode Exit fullscreen mode

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"}}
  ]
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
  '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.
Enter fullscreen mode Exit fullscreen mode

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-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.

Top comments (1)

Collapse
 
analista_83 profile image
Sammi De Blas •

Declaring caps in JSON is the right call given vendors never ship them in exports - one gap to close: quotas reset on a schedule (calendar month, rolling window, weekly), so a static cap file drifts the moment the window rolls; storing the reset timestamp alongside each declared limit and having the tool recompute remaining from now turns headroom from a snapshot into something that is correct at dispatch time.