feat(usage): show Codex and Claude subscription limits on a Limits tab

[juliusmarminge]

Closes #228.

Users on Codex or Claude Code subscriptions could not see how much of their quota was left, or when it resets, without leaving T3 Code. And a user whose CLIs route through a CLIProxyAPI hub could not see it at all: the Claude CLI treats the proxy token as an API key, and the hub's Codex login is not the one on disk.

What changed

Limits tab on the Usage page (web) and a Limits card (mobile), next to Cost and Tokens. Each provider that knows its subscription usage gets a section with one row per window: label and percent, a bar spanning the whole window with a hairline at the elapsed share ("where even spending would be"), a pace icon, and a reset countdown. Hover a bar for the exact reset time in your configured clock format. Emails are blurred until clicked, as in provider settings.

Each driver owns its data. checkProvider returns usageLimits on the driver's own ServerProvider snapshot — Codex from account/rateLimits/read during the probe it already runs, Claude from the SDK's get_usage control request on the capabilities query it already opens. Adapters normalise their turn-driven rate-limit events at the boundary into a typed ProviderUsageLimitsUpdate, and a ~40-line driver-blind ingestion layer folds them onto the owning instance through applyUsageLimits, so bars move mid-turn without a central service that switches on driver kind. Claude's model-scoped weekly bucket (Fable today) is read from rate_limits.model_scoped[]; the probe records the model's name so the streamed seven_day_overage_included event lands on the same row.

CLIProxyAPI hubs as usage-limit sources (second commit). settings.usageLimitSources entries are polled on the provider health interval and published over the config stream, gated by a client capability flag the way environment themes are. Not a provider — nothing here can run a turn, and one source reports many accounts. The management key goes to the secret store; settings keep a redaction marker. Hub accounts show under the hub's name, badged via CLIProxyAPI so a pooled account is not mistaken for the local login. Add CLIProxyAPI hub on the view adds one; Remove confirms before deleting the key.

Cursor, Grok, OpenCode, and Antigravity report nothing — their drivers never set usageLimits, so they have no row. Adding one later is "return usageLimits from checkProvider" with no central change.

Provenance

Distilled from two earlier PRs rather than merged from either:

• feat: display provider usage limits in settings #1732 by @Aditya190803 — the server model: limits on each provider's snapshot, the contract shape, the Codex app-server read, the per-provider rows and threshold colours. Its Claude path scraped claude --print /usage output that current CLIs no longer print, and its Cursor/Grok paths drove interactive TUIs; those are replaced or left out, and are welcome back as follow-ups against checkProvider if a non-scraping source appears.
• feat(usage): Limits tab with provider quota windows and Codex banked resets #9421 by @StiensWout — the Limits-tab placement, the window-bar-with-elapsed-marker design, the pace maths in packages/shared, and anchoring countdowns to render time. Its central UsageLimitsService and reset-credit redemption are not carried over.

Both are co-authors on the first commit.

Screenshots

Cost (unchanged)	Limits

Add a hub	Remove confirms

The local Codex row shows a 401 because that box's ~/.codex login is revoked; the same account via the hub is healthy. The local Claude row is an API-key session (proxy token), so it says so.

Verification

• Focused tests: managed-provider merge (11), Claude and Codex mappers (13), adapter event join (1), contract forward-compat (12), shared selection/pace (7), hub mapper (2), settings map replacement (24), UsagePage (4). Server, web, mobile, client-runtime, contracts typecheck clean apart from pre-existing yauzl / mobile-markdown-text errors on main.
• Exercised on a real server against a live CLIProxyAPI hub with four accounts: add and remove through the UI, key redaction on disk, refresh on the Limits tab re-reads the hub, Fable row from the hub's fable window.
• Not verified live: real Claude get_usage windows (every Claude login on the test box goes through the hub, so the CLI reports API-key mode). The mapper is tested against the SDK's documented shape and the CLI's actual model_scoped output; the bars are proven with stubbed data.

Follow-ups

• Reset-credit redemption from feat(usage): Limits tab with provider quota windows and Codex banked resets #9421.
• The hub's routing view (which account a model currently burns) — belongs near the composer, not here.
• Cursor / Grok rows if a non-scraping source exists.

Written by Claude Fable 5 via Claude Code, with the design and server model from the two PRs above.

---

Note

Medium Risk
Touches provider probes, runtime event shape (limits vs rateLimits), config streaming, and secret-store settings—clients must opt into new events; incorrect merge logic could show stale or wrong quota.

Overview
Adds a Limits view on Usage (web tab + mobile section) that shows subscription quota windows per connected environment—bars, pace vs. elapsed time, and reset countdowns—using shared helpers from @t3tools/shared/usageLimits.

Provider snapshots now carry normalized usageLimits: Codex reads account/rateLimits/read on probe; Claude adds SDK get_usage on the capabilities probe and maps streamed rate_limit_event into the same window ids (including model-scoped weekly via probe-recorded names). account.rate-limits.updated emits typed limits instead of raw payloads; ProviderUsageLimitsIngestion merges updates through ServerProviderShape.applyUsageLimits on makeManagedServerProvider (sparse merge by window id, keep last good bars on probe failure).

CLIProxyAPI hubs can be configured under settings.usageLimitSources (management key in secret store, redacted on disk). UsageLimitSources polls hubs and streams usageLimitSourcesUpdated when clients opt in via capability/subscription flags; refresh providers also refreshes sources. Web UI can add/remove hubs; mobile shows pooled accounts without emails.

^{Reviewed by Cursor Bugbot for commit 20594ca. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add Codex and Claude subscription limits to a Limits tab

• Introduces structured usage-limit schemas and normalized windows for Codex and Claude providers, replacing untyped rate-limit payloads.
• Provider adapters map streamed rate-limit events and probe responses into normalized usage windows; a new ingestion service folds live updates into provider snapshots without blocking probe refreshes.
• Adds CLIProxyAPI usage-limit sources configured via server settings, with management keys stored in the secret store and redacted for clients.
• Web and mobile apps gain a Limits view with quota bars, pacing indicators, and reset tooltips; clients opt in via the usageLimitSources capability.
• Risk: AccountRateLimitsUpdatedPayload replaces the untyped rateLimits field with a structured limits field using ProviderUsageLimitsUpdate; settings persistence now writes management keys to the secret store and only persists redaction markers in usageLimitSources.

^{Macroscope summarized 20594ca.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.7 KiB	13.7 KiB	−2 B (−0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.0 KiB	7.0 KiB	−2 B (−0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.7 KiB	6.7 KiB	0 B (0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	58.5 KiB	58.5 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	10	10	0 (0.0%)	21	✅
Claude	Total thread wire	13.8 KiB	13.6 KiB	−166 B (−1.2%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.0 KiB	7.0 KiB	−2 B (−0.0%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.7 KiB	6.6 KiB	−164 B (−2.4%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	59.3 KiB	57.9 KiB	−1.4 KiB (−2.4%)	66.4 KiB	✅
Claude	Live turn messages	10	10	0 (0.0%)	21	✅

Baseline: 80b5373 · PR result: 20594ca · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 113.8 KiB
• Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{Bugbot Autofix is ON, but a cloud agent failed to start.}

^{Reviewed by Cursor Bugbot for commit 0786184. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds a new Limits capability, changes provider probing and live runtime updates, and introduces an authenticated CLIProxyAPI integration with persistent secret handling. The breadth of the runtime and security-sensitive changes warrants human review.

^{You can add or adjust custom eligibility rules. Learn more.}