#1766: feat(ux): surface live provider usage/quota ambiently in the WebUI/Mac app — extend /api/provider/quota beyond OpenRouter and add a glanceable topbar indicator (CLI parity)

Summary

Surface live usage / quota / rate-limit information ambiently in the WebUI (and therefore the Mac Swift app) the same way Terminal Hermes does today, so users can see at a glance how close they are to their provider ceiling without opening Settings → Providers or running a CLI command.

Reporter: Cygnus (Discord; please ping in replies) via the WebUI testers thread.

Why — verbatim from Cygnus

I don't know if there are plans to show you how you're doing on usage with the AI you're using, but since Terminal Hermes shows it, I figure it's planned for the Mac app too? I hope? (May 7 2026, 00:15 UTC)

Note: this is a WebUI feature, not a Mac-app feature. The Mac Swift app is a WKWebView wrapper around the WebUI, so anything we expose in WebUI HTML automatically shows up in the Mac app. No native Swift work needed.

Current state

We have the foundational piece. PR #1671 (closed May 04 2026, feat by @Michaelyklam) added:

• GET /api/provider/quota endpoint (api/providers.py:361 get_provider_quota)
• An "Active provider quota" card in Settings → Providers showing remaining/used/limit
• OpenRouter support via the documented https://openrouter.ai/api/v1/key endpoint
• Explicit unsupported state for OpenAI / Anthropic (their per-call rate-limit headers aren't yet captured)

What's missing:

1. Ambient surface. The card lives in Settings → Providers — three navigation steps deep. Cygnus's framing ("how you're doing on usage") suggests a glanceable indicator, not a settings panel. Terminal Hermes shows usage in the chat surface itself (status footer / activity banner).

2. Provider coverage. OpenRouter only. Cygnus is on OpenAI Codex OAuth (per her companion message about Codex usage-exhaustion silent failures). Anthropic, OpenAI, Codex OAuth, Gemini, Grok, Nous Portal, Z.AI all show "unsupported". Most users are not on OpenRouter, so this card is empty for the majority.

3. No Codex OAuth usage view at all. Codex OAuth has a usage_overview endpoint (returns plan, weekly window remaining, daily window remaining, monthly tokens) — but the WebUI doesn't call it. The CLI's hermes auth status openai-codex does call it, which is what Cygnus is comparing against when she says "Terminal Hermes shows it".

What we should ship

Phase 1 — extend provider coverage in /api/provider/quota

For each provider with a documented quota / usage endpoint, add a branch in api/providers.py:get_provider_quota:

Provider	Endpoint	Returns
OpenRouter	https://openrouter.ai/api/v1/key	credits remaining/used/limit (already shipped in #1671)
OpenAI Codex OAuth	(Codex internal usage-overview API — same one hermes auth status openai-codex hits)	plan, weekly window (used / total / resets_at), daily window, monthly tokens
Anthropic API key	https://api.anthropic.com/v1/organizations/usage (admin org keys only)	input/output tokens used per window
Anthropic OAuth (Claude.ai)	(whatever path the Mac CLI uses — needs reverse-engineering or might require capturing per-call headers)	usage % of plan
OpenAI API key	rate-limit response headers (x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens) — captured per-stream rather than via a separate endpoint	last-known remaining requests/tokens

OpenAI/Anthropic API-key cases require capturing rate-limit response headers from the stream and stashing them somewhere the quota endpoint can read — defer to a follow-up if the additive scope is too large for one PR. Codex OAuth is the highest-value addition (it's what Cygnus and a lot of testers are using).

Phase 2 — ambient surface

Add a small status indicator near the model picker in the topbar that shows:

• Provider display name
• A compact remaining-usage bar (or remaining %, or remaining $, or remaining tokens — whichever the provider's quota shape supports)
• Tooltip with full breakdown

Hide entirely when the provider is unsupported or quota fetch fails (don't show an error — just don't render). Click target opens Settings → Providers's quota card.

Optional: a small live counter that updates after each chat turn for providers that return rate-limit headers in stream responses (OpenAI / Anthropic API key paths).

Phase 3 — refresh policy

Currently the quota card refreshes only when the Providers panel loads. Phase 2's ambient indicator needs:

• Refresh on app load (already wired)
• Refresh after each completed chat turn (cheap — one HTTP call to a documented endpoint)
• Optional: refresh on visibilitychange so when the user comes back to the tab it's fresh

The quota endpoint's 3s timeout in #1671 is already conservative, so per-turn refresh won't add measurable latency.

Severity

M3 / enhancement — no functional break, but a visible discoverability gap vs. the CLI experience. Cygnus's framing ("I hope?") signals user expectation that the WebUI/Mac app is at parity with the CLI on basic operational visibility.

Reporter

@cygnusignis via WebUI Discord testers thread, May 7 2026.

Related

• #1671 (merged) — initial OpenRouter quota card in Settings (foundation this issue builds on)
• #706 (open / tracking) — meta issue for remaining quota/rate-limit visibility
• #1617 (closed) — TPS display feature request (declined, but adjacent surface)
• Companion issue being filed for Codex OAuth usage-exhaustion silent failures — fixing one without the other still leaves users confused about why the app stopped working.