Provider plan limits: show rolling Codex and Claude quota headroom

[BarretoDiego]

The problem

The Usage page tells me what agents already consumed in tokens and API-equivalent cost. It does not answer the operational question that decides whether the next turn will run:

How much headroom is left in each provider subscription window, on each configured account?

Codex and Claude expose rolling plan limits, but today the user has to leave T3 Code or wait for a provider-side warning to discover that a 5-hour or weekly window is nearly exhausted. Multi-account setups make that worse: a personal Codex account and a work Codex account must never be merged into one percentage.

What I built

A small plan-limit ring beside Settings and Usage. It summarizes the most constrained active window across connected environments. Clicking it opens the full provider/account breakdown.

Screenshots — multi-account plan limits

The footer meter expands into provider-instance snapshots. Each account keeps its own plan, rolling windows, reset times, and warning state.

Compact summary	Configured provider instances
The most constrained active window stays visible without opening another page.	Instance display names map directly to the independent rows shown in the meter.

Manual refresh updates every account that has an active provider session, preserves the last known snapshot for unavailable accounts, and explains partial failures.

Provider-reported limits, not local estimates

This feature does not infer quota from token history. The server normalizes what each provider reports:

• Claude: 5-hour, weekly, model-specific, and extra-usage windows when present.
• Codex: primary/secondary windows plus named workspace or spend buckets when present.
• Providers or auth modes without subscription limits simply do not appear.

Each window carries its label, used percentage, observation time, and reset time. Expired windows render as reset until the provider reports a new observation instead of repeating stale utilization.

Accounts stay separate

Limits are keyed by provider instance, not only by driver kind. Codex - Pessoal, Codex - FieldPRO, and any other configured instance keep independent snapshots, labels, and reset windows.

The on-disk cache is also identity-checked against the instance id, driver, and continuation/account home before hydration. Changing the account or home clears the previous observation instead of showing one account’s quota under another account’s name.

Refresh without starting a throwaway turn

Provider events update the snapshot while an agent works. The popover also has an explicit refresh action:

• Codex uses account/rateLimits/read on an active app-server session.
• Claude requests a fresh usage snapshot from an active provider session.
• An unavailable account does not prevent the other accounts from refreshing.
• If an account has no active session, the last known observation stays visible and the UI explains that the provider needs to run first.

There is no background polling loop and refresh does not create a fake conversation turn.

Surfaces

• Web/desktop: summary ring and detailed popover in the sidebar footer.
• Mobile: the Usage route renders the same per-environment, per-provider-account windows.
• Server/contracts: typed provider snapshots, runtime events, refresh RPC, authorization, persistence, and account-safe cache hydration.

The existing local Usage analytics page remains separate. Usage history answers “what did I spend?”; plan limits answer “can this subscription keep working right now?”

Branch and review layers

Working branch: feat/refresh-provider-plan-limits

The implementation is layered as:

1. 54a0bcc71 — normalized provider plan limits, server ingestion/cache, sidebar meter, and mobile view
2. 95c630fc0 — preserve limits per provider account/instance
3. afa4b8858 — explicit refresh path and fresh provider snapshots

Focused coverage includes normalization/merge/reset behavior, provider registry hydration and identity mismatch, Codex and Claude ingestion, refresh RPC behavior, sidebar projection, contracts, and mobile rendering logic.

Relationship to the existing idea

Discussion #7833 asks for a usage tracker similar to provider status bars. This proposal is the concrete provider-reported quota side of that idea and is intentionally complementary to T3 Code’s local usage ledger rather than a replacement for it.

Product questions

1. Is the sidebar footer the right always-visible home for the summary?
2. Should manual refresh remain active-session-only, or should T3 own short-lived probe sessions for installed providers?
3. Do maintainers want the web/server path first and mobile split into a follow-up PR?

I am happy to split the branch along the layers above. The main thing I would like to preserve is account isolation: combining same-provider accounts makes the meter look simpler while giving users the wrong operational answer.