{"slug": "stop-finding-out-you-re-rate-limited-mid-task-check-the-headroom-first", "title": "Stop finding out you're rate-limited mid-task. Check the headroom first.", "summary": "A developer released blackbox-bill v0.3.0, an open-source, zero-dependency Python tool that reports per-account quota headroom before a task is dispatched, rather than diagnosing the bill afterward. The tool subtracts observed usage from user-declared caps in a limits.json file, flags each quota pool as OK, LOW, EXHAUSTED or UNLIMITED, and with --task-in/--task-out re-prices a planned task under each account's rate card to recommend which account can absorb it. It remains a read-only billing-attribution ledger with no enforcement or blocking.", "body_md": "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.\"*\n\n`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.\n\n```\npip install blackbox-bill\n```\n\nZero 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.)\n\nBilling 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:\n\n```\nblackbox-bill headroom --csv export.csv --limits-file limits.json\naccount 'cursor-pro' (plan cursor:pro, 3 bill row(s))\n  pool             consumed      limit  remaining   remaining               status\n  api-key             $0.00  unlimited  unlimited   [????????????????????]    n/a  UNLIMITED\n  cursor-models      $30.00    $500.00    $470.00   [###################-]  94.0%  OK\n  other-models      $120.00    $125.00      $5.00   [#-------------------]   4.0%  LOW\n```\n\nPools 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:\n\n```\n{\n  \"accounts\": [\n    {\"name\": \"cursor-pro\", \"plan\": \"cursor:pro\",\n     \"limits\": {\"cursor-models\": 500.0, \"other-models\": 125.0, \"api-key\": null}},\n    {\"name\": \"shared-api-key\", \"plan\": \"api-only\",\n     \"limits\": {\"api-key\": 200.0},\n     \"match\": {\"column\": \"account\", \"value\": \"shared-api-key\"}}\n  ]\n}\n```\n\nNo CSV yet this cycle? Run it limits-only — the dashboard shows your declared caps and you re-run with the export later.\n\nPlanning 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:\n\n```\nblackbox-bill headroom --csv export.csv --limits-file limits.json \\\n    --task-in 1000000 --task-out 250000 --task-pool other-models\n'cursor-pro'         est $10.00  DOES NOT FIT (remaining $-5.00)\n  'shared-api-key'     cannot price: no declared limit for pool 'other-models'\n\nWARNING: no account has headroom for this task under the declared limits.\nTop up, switch plan, or shrink the task before you dispatch — not after\nyou're stuck mid task.\n```\n\nOr, 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.\n\nv0.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.\n\nThe 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.\n\n`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.\nThe 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.", "url": "https://wpnews.pro/news/stop-finding-out-you-re-rate-limited-mid-task-check-the-headroom-first", "canonical_source": "https://dev.to/haoli/stop-finding-out-youre-rate-limited-mid-task-check-the-headroom-first-10ak", "published_at": "2026-10-17 07:55:06+00:00", "updated_at": "2026-10-17 08:01:49.252928+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents", "mlops"], "entities": ["blackbox-bill", "GitHub", "Show HN", "Cursor"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/stop-finding-out-you-re-rate-limited-mid-task-check-the-headroom-first", "markdown": "https://wpnews.pro/news/stop-finding-out-you-re-rate-limited-mid-task-check-the-headroom-first.md", "text": "https://wpnews.pro/news/stop-finding-out-you-re-rate-limited-mid-task-check-the-headroom-first.txt", "jsonld": "https://wpnews.pro/news/stop-finding-out-you-re-rate-limited-mid-task-check-the-headroom-first.jsonld"}}