multi-provider-usage-widget

AI subscription usage limits for Claude, Codex, and SuperGrok — in one TUI.

A standalone terminal dashboard that shows your session and weekly usage limits for three AI subscriptions side-by-side, auto-refreshing on a timer:

• Claude (Pro/Max via Claude Code) — 5-hour session + 7-day weekly
• Codex (ChatGPT plan via the Codex CLI) — 5-hour + 7-day
• SuperGrok (xAI Grok CLI) — monthly credits used (the /usage show data)

It reads each provider's own credential file, calls the same usage endpoints the official CLIs use, and (optionally) refreshes expired OAuth tokens itself — writing the rotated tokens back so your real CLIs stay logged in.

┌ Claude (team) ────────┐┌ Codex (plus) ─────────┐┌ SuperGrok ────────────┐
│● OK · live · 14s ago  ││● OK · live · 31s ago  ││● OK · live · 5s ago   │
│5h ▕████░░░░░░▏  42%   ││5h ▕███████░░░▏  78%   ││credits ▕██░░░░░░▏ 11% │
│   resets 1h12m        ││   resets 2h44m        ││   resets 2d 14h       │
│7d ▕██░░░░░░░░▏  18%   ││7d ▕█░░░░░░░░░▏  12%   ││2114 / 20000 credits · │
│   resets 3d 5h        ││   resets 5d 1h        ││pay-as-you-go off      │
└───────────────────────┘└───────────────────────┘└───────────────────────┘
updated 14s ago · [q]uit  [r]efresh  [1/2/3] provider

Usage

cargo run --release            # the live, auto-refreshing TUI
cargo run -- --once            # fetch once, print a text summary, exit
cargo run -- --once --offline  # local files only — no network, no token refresh
cargo run -- --snapshot        # render one frame to stdout (no TTY); --size WxH
cargo run -- --help

Install the binary: cargo install --path . then run multi-provider-usage-widget.

Keys (TUI)

Key	Action
q / Esc / Ctrl-C	quit
r	refresh all
1 / 2 / 3	refresh Claude / Codex / SuperGrok

How usage is read

Provider	Source	Notes
Claude	GET api.anthropic.com/api/oauth/usage	aggressively rate-limited → polled no faster than every 5 min, with 429 backoff
Codex	GET chatgpt.com/backend-api/wham/usage	cheap status endpoint; falls back to the newest ~/.codex/sessions/**/rollout-*.jsonl snapshot when the live call fails
SuperGrok	GET cli-chat-proxy.grok.com/v1/billing	the data grok → /usage show shows: monthly credits used (%) + reset date. A plain GET — no query consumed.

Tokens come from ~/.claude/.credentials.json, ~/.codex/auth.json, and ~/.grok/auth.json. When a token is expired and auto_refresh_tokens is on, multi-provider-usage-widget runs the OAuth refresh flow and atomically writes the new tokens back to the native file (preserving all other fields), guarding against refresh-token rotation races with a file lock + re-read-before-refresh.

SuperGrok reports a single window — the monthly credit allotment (used / monthlyLimit) with the billing-period reset date. It has no 5-hour/weekly windows like the others; that's just how xAI exposes it.

Configuration

Optional, at ~/.config/multi-provider-usage-widget/config.toml. See config.toml.example for every field with defaults. Missing files/fields fall back to defaults.

Notes

• Logs go to ~/.cache/multi-provider-usage-widget/multi-provider-usage-widget.log (never stdout — the TUI owns the terminal).
• Credential files hold personal tokens; multi-provider-usage-widget never logs token values, preserves 0600 permissions, and only ever writes refreshed tokens back to the same file.
• API endpoints/client IDs are pinned in src/consts.rs; re-verify them after a CLI upgrade if a provider starts erroring.

Development

cargo test           # unit tests (time formatting, parsers, render, merge logic)
cargo clippy         # lint
cargo fmt            # format