feat: show Codex and Claude usage limits

[NicL9923]

Fixes #228.

What Changed

Adds provider subscription usage visibility for Codex and Claude.

• Extends provider snapshots with dynamic usage windows.
• Reads Codex limits from the typed account/rateLimits/read app-server method.
• Reads Claude limits from claude --print "/usage" --output-format json.
• Shows a compact remaining-percentage summary on collapsed provider rows.
• Shows full usage bars and reset timestamps in expanded provider details.
• Adds an opt-in client setting to show the active thread provider's limits in the existing context-window popover.
• Supports provider-specific windows, including Claude model-specific weekly limits.

Why

Provider limits are easy to exhaust without any explanation in T3 Code. Users currently have to leave the app and repeatedly run /usage or /status to understand why a session stopped responding or how much capacity remains.

Provider settings provide a consistent place to inspect limits. The optional chat presentation gives users who check frequently quicker access without changing what the context-window gauge represents.

Implementation Notes

• Usage travels through the existing provider snapshot and config stream. No new transport or persistence layer was added.
• Codex usage is requested concurrently with the existing app-server provider probe and only for ChatGPT subscription accounts.
• Claude usage uses the existing Effect child-process abstraction rather than PTY or TUI automation.
• Claude usage probes close stdin, disable user and claude.ai MCP servers, and are cached per provider instance for five minutes.
• Usage retrieval is best-effort. A timeout, unsupported account type, or changed output format omits usage without degrading provider readiness.
• The context-popover setting is client-local and defaults to off.

Out Of Scope

• Grok, Cursor, and OpenCode usage
• Credit balances, spend controls, and usage-based billing plans
• Persistent usage caches
• Interactive PTY/TUI scraping
• Changes to provider refresh cadence
• A separate usage ring or changes to what the context-window ring represents

This PR reports subscription rate-limit windows only. The Codex account/rateLimits/read response also carries credits, individualLimit, planType, spendControlReached, rateLimitReachedType, and a multi-bucket rateLimitsByLimitId view, none of which are read here.

Two consequences worth knowing: accounts on usage-based plans or running purely on credits show no usage rather than wrong usage, and a window that reads fully consumed does not by itself mean work is blocked when credits remain. Representing balances needs a currency-denominated contract shape rather than the current percent-only window, so it is left as a follow-up.

UI Changes

Settings > Providers

Collapsed provider rows show a compact summary such as:

Session 16% · Weekly (all models) 80% · Weekly (Fable) 68% remaining

Expanded provider details show the full progress bars and reset timestamps.

Before:

After:

Optional context popover

When enabled under General settings, the context-window popover includes a visually separated Provider limits section.

Before:

After:

Verification

• Focused contracts/server/web tests: 112 passed
• Contracts, server, and web typechecks passed (with three pre-existing upstream Effect suggestions outside this diff)
• Targeted lint and formatting passed
• Production web build passed
• Manually verified against live ChatGPT Plus and Claude Max subscriptions
• Confirmed Claude returns session, weekly-all-models, and model-specific weekly windows through the real Effect child-process path

Prior Work and Feedback

This builds on the original implementation work in #1732 by @Aditya190803 and the discussion in #228. @dtown123 also identified the current Claude JSON-envelope command used here.

The narrower implementation incorporates feedback from those threads by:

• using the existing provider snapshot flow instead of a persistence/repository refresh loop
• limiting support to reliable Codex and Claude sources rather than speculative Cursor/OpenCode or interactive Grok probing
• showing reset timestamps and explicitly labeling percentages as remaining
• supporting dynamic Claude buckets such as model-specific weekly limits
• keeping the chat presentation opt-in and visually separate from context-window usage
• caching successful identity-matched probes per instance, expiring failures immediately, and skipping subscription usage for API-key/Bedrock auth
• using the existing Effect child-process abstraction with scoped cancellation, closed stdin, no MCP startup, and the configured workspace cwd

Reviewer Notes

Claude Code currently returns usage as human-readable text inside a JSON result envelope. The parser intentionally fails closed: malformed JSON, changed output text, non-zero exits, and timeouts omit usage without changing provider health.

An independent Claude Opus 4.8 review found and prompted fixes for:

• uncached Claude usage probes
• unnecessary Codex rate-limit requests for non-subscription auth
• progressbar accessibility semantics
• missing Codex and Claude API-key integration coverage

A second Opus 4.8 review found no remaining blocking issues. Residual risk is limited to upstream Claude /usage wording changes, which fail closed.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Adds best-effort child-process and app-server probes on provider health checks; failures are isolated but Claude output parsing is brittle if upstream wording changes.

Overview
Adds subscription rate-limit visibility for Codex and Claude by extending provider snapshots with usageLimits (dynamic windows with used %, optional reset times) and surfacing them in Settings and optionally in chat.

Server: Codex probes account/rateLimits/read for ChatGPT accounts (2s timeout, concurrent with existing app-server probe). Claude runs --print /usage JSON plus auth status --json, parses human-readable output via providerUsageLimits, skips API key/Bedrock, verifies email against capabilities, and caches probes per instance in ClaudeDriver (5 min on success, immediate expiry on failure).

Contracts: New ServerProviderUsageLimits / window schema on ServerProvider; client setting showProviderUsageInContextPopover (default off).

Web: ProviderUsageRows / summary on provider cards; context-window popover can show a separated “Provider limits” section when the setting is enabled, keyed to the active thread’s provider instance.

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

Note

Show Codex and Claude subscription usage limits in the UI

• Adds probeClaudeUsageLimits to fetch Claude account identity and usage windows via --print /usage, with a 4s timeout and per-identity caching in ClaudeDriver.
• Adds Codex rate limit fetching in probeCodexAppServerProvider via account/rateLimits/read with a 2s timeout.
• Introduces usageLimitsFromCodexRateLimits and parseClaudeUsageLimitsJson in providerUsageLimits.ts to normalize provider-specific data into a shared ServerProviderUsageLimits contract shape.
• Renders usage windows with progress bars and reset times in ProviderUsageRows and ProviderUsageSummary components, surfaced in the context window popover and provider settings panel.
• Adds a showProviderUsageInContextPopover client setting (default false) to gate display of usage in the chat composer popover.

^{Macroscope summarized 752b4df.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8588ed13-1c59-432d-9fe2-dcccf0d2c48d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new user-facing feature (provider usage limits display) with substantial new logic including external API response parsing, new UI components, and cross-layer integration. New features of this scope warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[NicL9923]

@juliusmarminge could you or someone get some eyes on this please? I know, I know, but this functionality is legit the last major QoL thing for me (and at least a few others). Would (mostly) close out an OG issue too ;). More than happy to make any changes if needed quickly to get this in unless y'all just disagree with the entire concept, but I think I have something pretty sensible here

[jo-chemla]

Would it also make sense to surface the same session/weekly usage progress-bars charts following a /usage command in chat? Currently only the raw claude-cli output is shown, adding the progress-bars would make it a lot more readable and similar to original providers desktop apps.

You are currently using your subscription to power your Claude Code usage

Current session: 59% used · resets Jul 31, 3:10pm (Europe/Paris)
Current week (all models): 54% used · resets Aug 4, 3:59am (Europe/Paris)

What's contributing to your limits usage?
Approximate, based on local sessions on this machine — does not include other devices or claude.ai. Behaviors are independent characteristics, not a breakdown.
...

---
<
charts
>

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

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

[cursor]

Auth hang drops usage results

Medium Severity

probeClaudeUsageLimits applies one four-second timeoutOption around the combined /usage and auth status Effect.all. If auth status is still running when that budget elapses, the whole probe is interrupted and successful /usage output is discarded, so limits disappear even though usage already completed.

 

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

[NicL9923]

Closing in favor of #5684