Module usage 

Canonical in-memory representation of “how much have I used my plan”.

Each vendor’s snapshot lives in its own variant — this is deliberate. Anthropic exposes three windows + extra credits; OpenAI Codex exposes up to two windows + credit balance + message-count ranges; OpenRouter is a single credit-balance number with daily/weekly/monthly totals; Z.AI is a list of token + MCP buckets; DeepSeek is a credit balance; Kimi is a weekly quota plus a 5h rolling rate-limit window. Forcing them into a shared shape would either drop information or paper over genuine differences.

Renderers (widget tooltip, TUI tab) consume a VendorSnapshot directly, not a flattened shape — so each vendor controls its own presentation while sharing the pacing math, color thresholds, and Pango primitives.

Structs

AnthropicApiSnapshot

Anthropic Admin API — month-to-date spend (USD) from the cost report. The monthly limit is supplied from config (the API exposes neither the limit nor the remaining prepaid credit balance).

AnthropicSnapshot

Anthropic-specific snapshot — three rolling windows plus optional pay-as-you-go credit balance.

AntigravitySnapshot

Google Antigravity 2.0 / CLI snapshot. The API groups models into Gemini and third-party (Claude/GPT) buckets, and each group may carry a 5-hour and a weekly window — up to four, and not every product or plan offers all of them. Antigravity CLI 1.1.22 returns weekly buckets only, so every window is optional and a snapshot is valid when at least one arrived.

Cents

Money in minor currency units (historically always cents; see ExtraUsage::decimal_places for the actual scale) to dodge float roundoff.

CursorCreditGrant

One promo balance from Cursor’s spending page (GetClientVisibleCreditGrants). Amounts are USD cents. remaining_cents is the figure to the left of the slash ($21/$25).

CursorSnapshot

Cursor — the two included-usage pools the dashboard shows, from the undocumented cursor.com/api/usage-summary endpoint (the same one the dashboard’s own frontend calls), authenticated with the session token the Cursor IDE wrote to its local state.vscdb.

DeepInfraSnapshot

DeepInfra prepaid balance and current-month usage from the documented /payment/checklist and /payment/usage billing endpoints.

DeepseekSnapshot

DeepSeek — credit balance from /user/balance.

DevinSnapshot

Devin CLI quota snapshot. The CLI reports remaining percentages, while renderers and report consumers use consumed percentages consistently.

ExtraUsage

“Extra usage” pay-as-you-go block (claudebar’s extra_usage).

GrokSnapshot

xAI (Grok) — prepaid credit balance in USD, derived from the Management API’s total.val (USD cents, inverted-ledger; see grok::types).

GrokbotSnapshot

Grok Bot desktop app — the weekly included-usage pool from aiserver.v1.DashboardService/GetSandUsageStatus (Connect-RPC), read with the app’s own OAuth session. Distinct from GrokSnapshot (Management API prepaid dollars) and SuperGrokSnapshot (Grok Build subscription).

KiloSnapshot

Kilo Code — remaining credit balance from /api/profile/balance (USD). No purchased-total is exposed on that endpoint, so there’s no consumed-%.

KimiSnapshot

Kimi Code — weekly subscription quota plus a 5h rolling rate-limit window.

KiroSnapshot

Kiro CLI (AWS CodeWhisperer / Q Developer backend) — a single credit pool from AmazonCodeWhispererService.GetUsageLimits, the same call kiro-cli’s own /usage slash command makes. Authenticated with the AWS SSO OIDC bearer token kiro-cli already cached locally, refreshed with the paired refresh token when it’s close to expiry — see kiro::db and kiro::oauth.

LyceumSnapshot

Lyceum’s platform credit balance is denominated in USD, not a percentage quota.

MinimaxSnapshot

MiniMax Token Plan — /v1/token_plan/remains returns one row per model bucket (general for text/coding, video), and each row carries its own rolling interval window plus a weekly window.

ModelPoolWindow

One window of an Antigravity per-model pool, named by the response’s group display name. Its cadence is window.window_duration.

ModelStudioSnapshot

Alibaba Cloud Model Studio Token Plan — a 5-hour, a weekly and a monthly ratio window, any of which the console account may not report. An absent window is no-data (possibly unlimited), never 0%.

MoonshotSnapshot

Moonshot / Kimi — account balance from /v1/users/me/balance. Currency is USD (api.moonshot.ai) or CNY (api.moonshot.cn); there’s no currency field in the response, so it’s carried here from the region config.

MuseSnapshot

Muse Code subscription windows. Missing observations stay absent.

NovitaSnapshot

Novita AI — account balance from /openapi/v1/billing/balance/detail, with all amounts already converted from the API’s 1/10000-USD integers to USD.

OllamaCredits

OllamaModelUsage

One row of OllamaSnapshot::{session,weekly}_models. The API carries the per-model request count; the percentage of the window that this single model represents is not reported, so the renderer derives it locally.

OllamaSnapshot

Ollama Cloud — credit balances or legacy quota windows from ollama.com/api/balance. Older cached /api/usage payloads can also carry per-model counts and activity cost.

OpenAiCredits

OpenAiNamedLimit

A named limit that sits beside Codex’s main window — a reserved pool or a model-specific allowance. It can be exhausted while the headline window is nearly untouched, which is the case it exists to make visible.

OpenAiSnapshot

OpenAI Codex OAuth — exposes whichever rolling windows the API reports.

OpenAiUnavailableModel

A model the account cannot currently dispatch to.

OpenRouterSnapshot

OpenRouter — credit balance + lifetime/daily/weekly/monthly usage from /api/v1/credits and /api/v1/key.

OrcaRouterSnapshot

OrcaRouter — prepaid credit card from the one-api compatible dashboard billing endpoints (/v1/dashboard/billing/usage + /subscription), over an API key. Usage arrives in US cents (total_usage: 275 = $2.75); the subscription’s limit fields are USD and mean the total credit limit (remaining + used), with 100000000 as the unlimited sentinel.

ResetCredit

ResetCredits

Banked, user-redeemable quota resets — Codex’s “rate limit reset credits” and SuperGrok’s “remaining resets” are the same idea under two names: a count you have earned, each with its own expiry, redeemed by hand rather than arriving on the window’s own schedule. Distinct from a UsageWindow::resets_at, which needs no action and cannot be banked.

ScopedWindow

A usage window scoped to a specific model, labeled by the API (e.g. “Fable”). Weekly (7d) duration.

SuperGrokProduct

One SuperGrok product’s share of the current included-credit window.

SuperGrokSnapshot

SuperGrok subscription usage from Grok Build’s billing endpoint (ACP as fallback) plus banked remaining-resets. Distinct from GrokSnapshot (Management API prepaid balance).

SyntheticSnapshot

Synthetic subscription quota from the documented /v2/quotas subscription object.

UsageWindow

A single usage window — generic enough that every vendor with a notion of “% used vs. when does it reset” can express itself with it.

ZaiSnapshot

Z.AI / BigModel — list of buckets with discriminated types. We project the two we care about into named fields (5h tokens, weekly tokens, MCP).

Enums

AntigravitySource

Which path produced an AntigravitySnapshot. The local language server is the primary source; the remote API is the fallback for when no product is running, and the panel says so because the two can disagree briefly.

ExtraUsageStatus

OpenAiSource

SuperGrokPeriod

VendorSnapshot

Discriminated union of vendor-specific snapshots. The widget and TUI match on this to pick a renderer.

Functions

anthropic_severity

Worst-of severity class for the Waybar bar text color. Mirrors claudebar:606-620 — “extra usage only matters when a rate limit hits 100%”.

checked_reset_title

A provider’s own label for a banked reset, rendered verbatim in Pango bar markup and in the ;;-delimited desktop FORMAT protocol. Both vendors that carry one gate it here rather than each keeping a copy: an over-long or control-character-bearing title is dropped, leaving the expiry line alone, which still says everything the user has to act on.

finite_amount

Reject a non-finite monetary value. A NaN or infinity reaching a balance field means the payload was not what we think it is; displaying it as money (or caching it as authoritative) is worse than failing loudly.

fmt_minor

Format an amount in minor units with its own currency and scale.

parse_amount

Parse a monetary field that the wire encodes as a string. A malformed or empty value is a schema error, not a zero balance — silently reporting $0.00 for an error envelope is the failure mode this guards against.