A BB panel for what you are burning right now, how much of your plan is left, and how many tokens you have spent — across every provider you are signed in to, on every machine BB knows about.
Live throughput. A 15-minute chart of tokens as they are reported, binned per 10 seconds and stacked by provider, with the current rate over the trailing 60 seconds, the best rate seen in the window, and the threads doing the work. It updates every couple of seconds while a turn is running and settles when the machine goes quiet. Archived and deleted threads drop out immediately — they are history, not current burn. BB's token events are authoritative; for BB-launched ACP sessions whose bridges do not emit them, the plugin maps the provider thread id back to opencode's exact local counters or Cursor's text-derived estimate.
Provider limits. One pane, one row per provider: its plan, each rate-limit window (5-hour, weekly, monthly — whatever the provider reports), how much is left, and when it comes back. Every meter counts down — the ring, the bar, and the number all show what remains, the way each provider states its own limits. Cost-backed windows also show the amount used and the period cap. A provider bb ships stays listed even when it is not installed, because that is real news; a plugin-supplied provider such as Muse Code appears only once its plugin is installed.
On the primary machine, Codex adds purchased-credit balance, banked reset count and expiry, model-specific limit buckets, and any on-demand spend control the Codex backend reports. Claude adds the same banked-reset row: saved grant resets plus the unused weekly session reset (1/week) when Anthropic reports them.
Pooled accounts. When the Account Pooler routes a provider across several logins, one meter per provider stops describing what the next request will get: the account at the front of the failover order can be exhausted while the pool as a whole is fine. Such a provider becomes an overview instead of a stack of bars: one row per enabled account in failover order, each collapsed to the line that answers "can this account take work?" — whether it is serving, on standby or unavailable, and how much its tightest window has left. Opening a row shows the windows behind that answer. The account serving new requests opens by default, since it is the only one whose numbers describe the next request, and the provider's ring follows it rather than whichever login the CLI happens to hold. A pooled provider stays on the dashboard even when the host reports nothing for its local credentials, which is the normal state once routing is on.
The host and the provider's own CLI can only describe one login: the account this machine is signed into. That account keeps its named windows — Codex's per-model buckets and cost-backed periods among them — and is marked "signed in here"; the other accounts show what the pool knows, which is coarser but is the only view of a login this machine never held. A window the pool cannot yet name or time is left out rather than drawn as a full one, because the pool posts a slot as soon as a response header mentions it, before it knows the window's length or when it turns over.
Accounts are read from bb pool status --json on the machine bb runs on, so
nothing here touches the pool's stored tokens. Providers are matched by the
pooler's own names (codex, claude), and a provider whose routing switch is
off is left alone — bb still hands it its own credentials, so the pool's numbers
would describe traffic that is not flowing there. The pooler is experimental and
says its CLI can change between releases; every field is parsed defensively, and
a pool that cannot be read leaves the dashboard exactly as it was.
The totals row still aggregates each provider's host-reported windows, so "tightest" and "next reset" do not yet account for pooled accounts.
Token usage, for every provider. A 7 / 30 / 90-day multi-series chart of real token volume, broken out into total, uncached input, output, and cached, per provider. Total follows the provider's canonical count where one is available and includes cached input; the cached field is also retained as a breakdown. Cursor's ACP stores do not include token counters, so its series is estimated from the recorded conversation text. The data reads from two tiers:
- Transcript scanners for the agents that keep detailed local records —
Codex (
~/.codex, or$CODEX_HOME), Claude Code (~/.claude, or$CLAUDE_CONFIG_DIR), Cursor's ACP session stores, opencode (~/.local/share/opencode, or$XDG_DATA_HOME/opencode), and Muse Code (~/.local/share/muse, or$MUSE_HOME/$XDG_DATA_HOME). These give full history and exact per-day attribution, back to before you installed BB. - BB's own usage events for everything else. As soon as a provider emits
thread/tokenUsage/updated, an agent this plugin has never heard of — a new ACP agent, one you wrote yourself — lands in the chart automatically, with a name and a colour of its own. No release here required.
Providers with a dedicated scanner are excluded from the second tier, so nothing is counted twice.
Multi-machine. If you have more than one host paired, a machine picker switches the whole view between them.
It also contributes a homepage section and a sidebar accessory, so the tightest window follows you around without opening the panel.
From the BB marketplace:
bb plugin install provider-usageOr from a local checkout:
git clone https://github.com/braedonsaunders/bb-plugin-provider-usage.git
cd bb-plugin-provider-usage
npm install --include=dev
bb plugin install . --yesOpen Usage in the left sidebar.
bb usage # remaining quota, plans, reset windows
bb usage --json # same, machine-readable
bb usage live # what is being burned right now, by thread
bb usage tokens --days 30 # global token volume across providers
bb usage --machine <id-or-name> # read another paired hostAgents get the same data through the bundled usage skill, which is how a
long-running thread can decide whether to keep going or wait for a reset.
Subscription windows come from BB's own system.usageLimits for each signed-in
provider. On the primary machine, a read-only codex app-server request fills
in newer Codex fields that BB's provider-neutral schema does not yet carry, and
a single cached Claude OAuth usage read lifts banked-reset programs BB's
windows omit. Both use the existing provider sign-in and never read, store, or
return auth tokens. If the installed CLI or endpoint does not support the
request, the panel silently falls back to BB's regular windows.
The on-demand amount shown here is a provider-reported spend-control period. It is separate from organization-wide OpenAI Platform API billing. Exact Platform API spend comes from OpenAI's Costs API and requires an organization admin key; this plugin does not ask for or store one.
Token totals come from a background token-scan service that walks local
transcript files, caches per-file results in the plugin's SQLite database, and
re-syncs every 15 minutes. Only sources whose size or mtime changed are re-read,
so a large history stays cheap. Nothing is uploaded anywhere.
That per-file cache is also the ledger. Transcripts are evidence of usage, not the record of it: Codex prunes old rollouts, BB removes a worktree's thread files, a session gets cleared. A file that leaves disk keeps the days it already contributed until those days age out of the 90-day window, so the chart never revises history downwards for work that really happened. Claude responses are still deduplicated by message id across live and retained files, so a fragment that replays a response cannot count it twice.
The same pass asks BB for thread/tokenUsage/updated on any thread whose
provider has no dedicated scanner. Those events carry the thread's running
total rather than the turn's, so consecutive events are differenced; a total
that goes backwards means the thread was compacted or restarted upstream and is
read as a fresh total rather than a negative one.
Live throughput is a separate, deliberately different path: a
throughput-scan service follows thread/tokenUsage/updated for every provider
that emits it, polling every two seconds while a thread is working and every ten
when none is. Some ACP bridges currently omit that event. For BB-launched
opencode and Cursor sessions, a local fallback resolves BB's persisted
thread/identity to the matching provider session and reads only that session's
store. Native events always win, so the two paths never count the same thread.
Work run outside BB, such as an agent CLI in a bare terminal, remains excluded.
Attribution is the subtle part. Those events carry the thread's running total,
so consecutive events are differenced. The first event seen for a thread has
nothing to difference against, and providers report it very differently: BB's
Claude Code bridge has been seen emitting a single event whose running total is
98.7M and whose last is 55.9M — usage since the session resumed, hours of it,
not one step. Charting either figure raw drops tens of millions of tokens onto
one instant. So a thread's first event is charted only when the thread itself is
younger than the window, because then its whole history is inside the window by
definition; otherwise it becomes the baseline and every event after it
differences correctly. The cost is one uncharted turn per thread when the
service starts.
The two charts share one palette, seated per provider rather than per rank, so a provider is the same colour in both and keeps that colour as other series come and go. The slots are checked rather than eyeballed: each sits in its mode's lightness band, clears the chroma floor, holds 3:1 against the surface, and keeps neighbouring slots apart under simulated protanopia and deuteranopia.
A caveat worth stating plainly: the event fallback only sees what a provider
actually reports. Providers that neither emit thread/tokenUsage/updated nor
have a supported local store will show subscription windows but no token
series, and some agents (Factory Droid, Hermes) keep no usable per-turn token
record on disk at all.
npm install --include=dev
bb plugin install .
bb plugin devThis plugin was previously called dashboard and its CLI was bb dashboard.
The panel, data, and layout are unchanged — the id is now provider-usage and
the command is bb usage. If you installed the old one from a path, remove it
before installing this one:
bb plugin remove dashboard
bb plugin install provider-usageTo keep your token history, copy the old plugin's database across before installing:
cp ~/.bb/plugins/dashboard/data.db ~/.bb/plugins/provider-usage/data.dbIt is not the same plugin as the marketplace's usage, usage-page, or
usage-tracker entries, which track token spend and estimated API cost. This
one leads with remaining plan quota and reset windows, and reads token
volume off local transcripts rather than pricing it.
MIT © Braedon Saunders