usage-remaining

A Paseo plugin that shows how much AI usage you have left — right above the composer.

The original two-line display is preserved on Paseo Desktop, web, and compatible native clients:

• 5H — provider logos, colored remaining percentages, and session reset times
• WK — Claude, Fable, Codex, Grok, and Cursor (monthly) with their reset times

Green, yellow, and red percentages show remaining capacity. Refresh inline, or click
for the full dashboard. On narrow web screens the reset labels and refresh button
move out of the inline display; all providers still fit, and the dashboard has details.

On iOS, the colored two-row display stays above the input. Tap it to open all providers in a scrollable sheet.
Cards show each provider’s logo and name, colored remaining capacity, and one reset
label. Narrow screens stack the header above a 44px refresh button. The full
dashboard uses the same responsive cards. Failed refreshes preserve the last values
and show an error.

What it reads

Everything is read locally and read-only. No credentials are written, logged, or sent anywhere except each provider's own usage API.

Install

Requires Paseo 0.8.0 stable on the daemon and client. Early 0.8 betas use an older composer API. The last revision for Paseo 0.7 is commit 8e4da65.

1. In Paseo: Settings → Plugins → Enable plugins
2. In a terminal:

paseo plugin add Sundayable/paseo-usage-remaining

That's it. Open any workspace — the usage pill appears above the composer.

Update later with:

paseo plugin update usage-remaining

Behavior details

• Refreshes the display every 60s. Claude usage requests run at most every 5 min per token, including failures and manual refreshes. Concurrent callers share one request. A 429 honors Retry-After (one hour by default); a 403 is held for six hours. Attempts and cooldowns survive reloads.
• Claude follows the token that claude-paseo reads from claude.env, even when the daemon inherited an older token. Rows say workers when they use that token, or fallback when they use the interactive Keychain/credential-file login. The dashboard names the source, the fallback subscription type when available, and why worker usage is unavailable. A fallback can belong to a different organization and must not be interpreted as worker quota.
• Setup tokens can run Claude while lacking the user:profile scope required by the usage endpoint. When the worker usage lookup fails or is cooling down, the plugin sends one minimal Haiku request (max_tokens: 1, prompt .) at most every five minutes per token and reads the anthropic-ratelimit-unified-* response headers. This consumes a small amount of that worker account's quota, directly outside HQ accounting. The detail names this source. A missing weekly header is shown as unknown, never replaced with a personal account's weekly value. Probe attempts survive reloads; probe 429 responses honor Retry-After and authentication failures have a six-hour cooldown. Generated text and error bodies are discarded.
• Claude samples are bound to a token fingerprint, expire after six hours or their window reset, and keep their original observation time. Changing accounts cannot reuse another account's percentages. Old caches without credential provenance are discarded for Claude. A cached worker sample is preferred to switching to a different account on a transient failure.
• Optional local account names live in ~/.paseo/usage-remaining.accounts.json: a JSON object mapping the first 16 hexadecimal characters of SHA-256(token) to a display name. Names appear in dashboard details only when the current file token matches. These are operator-provided labels, not API-verified organization identities. Never put a token in this file or commit it.
• The wide inline display and dashboard include a manual refresh button. A manual refresh re-queries Codex, Grok, and Cursor immediately; Claude still keeps its 5-minute minimum interval and any active cooldown. After a manual refresh, the button shows a shared 2-minute countdown before it can be pressed again.
• If a provider's token is mid-rotation (common while agents run), the plugin serves the last good value from a small local cache ($PASEO_HOME/usage-remaining.cache.json) instead of flickering to "—". Absolute reset timestamps are cached, so countdown labels keep updating even while the provider API is rate-limited.
• Provider windows that never had data (not signed in) are omitted from the inline display and explained in the dashboard. If none are available, it says Usage unavailable.
• A provider that answered recently but stops answering (for example right after its window resets, before the API reports the new period) stays in the strip as a dimmed — chip instead of silently disappearing. The dashboard card says window reset · waiting for provider.
• Every provider request has a 15-second deadline so one slow API cannot stall the whole strip, and each failure is logged as [usage-remaining] <provider>: … in the Paseo daemon log (~/.paseo/daemon.log) so a missing chip can be diagnosed from the log alone.
• The original rich display uses the 0.8 web compatibility adapter described below. Native clients use a guarded native adapter to restore the same colored two-row display, with a scrollable sheet on tap.
• Source changes require npm run typecheck followed by paseo plugin reload usage-remaining. The 0.8.0 desktop client updates without a daemon restart.
• A cached row is dropped once its own reset time passes, so a stale pre-reset % is never shown next to now.
• On native clients the plugin hides Paseo's own git diff badge (+123 -45) from the
  composer track, so the phone shows usage only. Paseo 0.8 has no setting for that
  badge, so the native adapter hides the node and restores it when the plugin is
  disabled or unloaded. Desktop and web keep the badge.

Paseo 0.8 web compatibility

Paseo 0.8 replaced arbitrary composer components with fixed button descriptors.
Its normal button forces muted text, a 160px maximum width, and a clipped 16px icon.
The plugin registers through the supported button API, then mounts the original
React Native usage component in its own web icon slot. The original button's
opaque surface, border, and rounded frame remain behind the colored data.

Paseo's track normally floats absolutely over the transcript. A two-row widget
must not remain in that overlay: client/web-composer.ts makes the containing
track a normal, nonshrinking flex row with an opaque background. The transcript
viewport gives up exactly the track's height; wrapping provider chips or adjacent
task/diff badges increases the reserved space instead of covering chat text.

The adapter verifies the expected direct ancestors (including the desktop's
display: contents tooltip wrapper) before expanding anything. It changes only
this agent's containing track and its own button, and restores all changed styles
and accessibility attributes on unmount. If safe space cannot be reserved, it
leaves the standard button intact. Native clients use client/native-composer.ts to expand the owned native icon slot
and reserve track height through setNativeProps. The host icon slot centers its
single child, so the adapter also sets alignItems: 'flex-start' and the two rows
start at the button's own text edge instead of sitting in a wide centered gutter. It validates the observed Fabric
host structure before touching any styles and restores changed properties on
teardown. This relies on internal React Native host handles; unknown structures
retain the standard button and sheet. Actual iPhone verification covered the
restored always-visible display, app re-entry, opening/closing the sheet, and
scrolling through Cursor. Android remains unverified.
Future host changes require rechecking the adapter against the installed app.

Caveats

• Paseo's plugin API is experimental; a Paseo update may require a plugin update. This revision uses the stable 0.8 button registration API (button, update, remove) and runtime-entry layout (index.client.tsx / index.server.ts, client/ server/ shared/) and declares requirements.paseo >=0.8.0.
• Provider usage endpoints are unofficial and can change without notice.
• Cursor team-billed seats return no plan usage from the endpoint this plugin uses.

Credits

Provider endpoint and credential-file handling is based on Paseo's own open-source quota-fetcher (getpaseo/paseo, Apache-2.0). Provider logos are the trademarks of their respective owners, used for identification only.

License

MIT

Development

npm ci
npm run typecheck
npm test
paseo plugin reload usage-remaining

Tests use Node.js 22.18+ native TypeScript stripping. They cover paginated agent
bootstrap, live updates, moving/removing agents, teardown races, unavailable usage,
and scoped web style restoration/fallback.
SDK dependencies are pinned to the installed stable Paseo 0.8.0 API; the live docs may
show a newer subscription API that is not yet in that release.