feat: display provider usage limits in settings

[Aditya190803]

Fixes #228.

What Changed

Added provider usage limits to the settings flow end to end for all 4 providers (Codex, Claude, Cursor, OpenCode):

• the shared contract now includes the usage-limits schema
• the server persists and exposes provider usage limits
• the web app renders the limits in Settings

Note: For OpenCode, only the official OpenCode-managed providers (OpenCode Go, OpenCode Zen) are shown.

Why

Users need a visible place to confirm provider usage limits without digging through logs or backend state. This keeps the value available across sessions and makes the current limits easy to inspect from the UI.

UI Changes

The Settings panel now shows provider usage limits in the provider section.

Checklist

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

---

Note

Medium Risk
Provider status checks now spawn PTY/CLI probes and merge live rate-limit events into published snapshots; failures degrade to “unavailable” but add complexity and timing sensitivity around concurrent refreshes.

Overview
Adds provider subscription quota data to provider snapshots and surfaces it in the mobile Usage screen, with server-side probing and live refresh so limits stay current between status checks.

Server: Each major driver (Claude, Codex, Cursor, Grok, OpenCode) now attaches usageLimits during status probes—via Codex app-server account/rateLimits/read, Claude claude --print /usage, Cursor/Grok PTY /usage TUI automation, and OpenCode Go/Zen inventory fields. Optional PtyAdapter is threaded into Claude/Cursor/Grok driver checks so PTY-based probes work when the server layer provides it. applyUsageLimits on managed provider snapshots patches quota windows from runtime account.rate-limits.updated events (ProviderUsageLimitsIngestionLive), with epoch merging so in-flight probes do not overwrite fresher live updates.

Mobile: New Provider limits section on the usage route shows per-environment provider bars, reset dates, and notices (e.g. Grok free tier, unavailable API-key accounts).

Hygiene: Ignores .claude-work-test/ so Claude usage probe tests do not commit session files.

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

Note

Add provider usage limits display to Usage page with CLI probing and runtime ingestion

• Adds ServerProviderUsageLimits schema to server.ts with validated usage windows (session, weekly, monthly), percent clamping to 0–100, and forward-compatible decoding that drops invalid windows instead of failing the provider
• Adds per-provider usage probes that launch provider CLIs in a PTY and parse their /usage or TUI output: Claude (claudeUsageProbe.ts, 15s timeout), Cursor (cursorUsageProbe.ts, 25s timeout), Grok (grokTuiUsageProbe.ts, 10s timeout), Codex via app server rate-limits API (codexUsageProbe.ts), and OpenCode managed providers (openCodeUsageLimits.ts)
• Adds ProviderUsageLimitsIngestionLive layer in server.ts that subscribes to account.rate-limits.updated events, parses runtime telemetry via runtimeUsageLimits.ts, and calls applyUsageLimits on the provider instance to patch live snapshots
• Updates makeManagedServerProvider.ts to expose applyUsageLimits, track per-window patch epochs, and preserve live-patched usage windows across concurrent refresh and enrichment
• Renders usage bars with colored thresholds, reset dates, and tier notices in ProviderQuotaLimits.tsx on the web Usage page and in UsageRouteScreen.tsx on mobile
• Improves PTY adapters: NodePtyAdapter.ts and BunPtyAdapter.ts now cache and replay exit events to late subscribers; Windows kill() uses taskkill /T /F for process-tree termination
• Behavioral Change: NodePtyProcess constructor now requires a platform argument; Windows kill behavior switched from process.kill to taskkill with process.kill fallback. Provider snapshots now carry an optional usageLimits field; invalid usage windows are silently dropped during decode rather than failing the provider

^{Macroscope summarized ea3c1ce.}

---

[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: 1ee2bf19-dba6-4b48-840f-cced02ce3deb

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

Warning

Your free Security trial is over. An organization admin can activate Security or dismiss this notice.

---

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

[Aditya190803]

For now, I’ve added two images to illustrate the UI:

1. Free tier view

This screenshot reflects my current setup. I don’t have subscriptions to Codex or Claude Code, I’m using Copilot Pro (available to me as a student). It shows how the weekly usage limit appears in the interface.

2. Pro tier (mocked example)

This second screenshot uses dummy data to demonstrate how the UI could look for users on a Pro plan (Codex or Claude Code). It includes both session-based limits and weekly limits for clarity.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 80515efa38

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a substantial cross-provider usage-limit capability with new CLI/PTY probes, live runtime ingestion, shared snapshot concurrency logic, and web/mobile UI changes. Its broad production impact and several unresolved comments describing concrete runtime or display risks require human review.

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

[Aditya190803]

Hey @juliusmarminge, could you take a look at this PR when you get a moment? Thanks!

[Marve10s]

Randomly found this PR because wanted to add usage to T3. I think this is great as a user but also I think the UI should match the Codex App usage,it's minimal and clean, would be better than AI tabs

You would need to redo the settings button though,something Julius needs to approve. I genuinely think settings button should match Codex App, would love to open PR for that.

[Marve10s]

A few concerns after checking the code:

1. Codex can prefer stale persisted usage over freshly probed usage in the same refresh path.
   checkCodexProviderStatus() reads cachedUsageLimits first, then later resolves account state, but ultimately uses cachedUsageLimits ?? accountUsageLimits. That means a refresh can still emit an older persisted value even when the same refresh just fetched newer limits from the provider probe. If the goal is to show the freshest available snapshot, I think the precedence likely needs to be reversed, or persisted data should only be used when no fresh usage was fetched.
2. The persisted cache looks too coarse-grained for account/config changes.
   The new table is keyed only by provider_name, and the repo API is also getByProvider only. That seems risky if the user changes auth state, swaps Codex homePath, changes binary path, or otherwise changes the effective account behind a provider. In those cases we can still surface previously persisted usage for the provider even though it may belong to a different account/config. Is that safe, or should this cache be scoped more tightly (for example by provider + account/config fingerprint) or suppressed when provider health/auth no longer matches the cached source?
3. A usage-limit update currently looks like it can trigger full provider refresh work.
   ProviderService persists account.rate-limits.updated, then ProviderRegistry listens to repository changes and calls refresh(change.provider). That refresh path eventually reruns the provider's checkProvider flow rather than just updating already-known snapshot state. For a quota-bar style UI update, this feels heavier than necessary and could add extra CLI churn to a hot path. Would it be simpler to keep usage attached to the provider snapshot/update flow directly instead of going through persistence -> repository stream -> provider refresh?

I can test further and commit to this PR if you're okay with it, @Aditya190803. Genuinely want to see this merged - it would be super useful

[juliusmarminge]

this is on my list to review still! Just dealing with some larger prep work so haven't had time yet.

As for the "it must be more visible and sjhould be 1:1 like codex app":

How often do you guys check your limits to warrant it being one click ??? I check it at most a few times a week, so hiding it in settings next to the provider status is fine!

[Marve10s]

this is on my list to review still! Just dealing with some larger prep work so haven't had time yet.

As for the "it must be more visible and sjhould be 1:1 like codex app":

How often do you guys check your limits to warrant it being one click ??? I check it at most a few times a week, so hiding it in settings next to the provider status is fine!

I've been checking usage a lot in Codex - a couple of times daily since I was on the $20 plan with 2x limits till April, so I was curious how it was going. My take is that the current settings are genuinely fine, but I think it'll get crowded soon. With usage, OpenCode and Cursor support, and I'm sure there are PRs that extend the settings further it's going to contain a lot of content before long.
Codex shows a small tab with everything you need: usage, general info, and language (something I'd tuck away in settings). I think the Cursor settings approach is a good reference here too.

[juliusmarminge]

Yes when the single settings page gets too large we'll split it to subpages. We already did the work adding the sidebar when adding the archive

[juliusmarminge]

can't see claude limits:

[juliusmarminge]

implementation seems way overcomplicated.

why cache the data? the provider check runs once per minute. we can get fresh data on every tick?

how i imaagined this working:

• extend the checkProvider probe in ServerProvider to include a new usageLimits property.
• on the auth check probes (app server / claude), extract usage data
• stream it down to client as part of the normal provider snapshot
• render the UI on settings page

given i haven't looked into exactly what's possible to probe and not, why is this PR so much more than that?

[Aditya190803]

Follow-up stacked on this PR: remaining session/weekly usage in the chat box, current provider only.

Stacked PR: #8445

• Opt-in via Settings → General → Show usage in chat (default off)
• Hidden until the thread has sent its first message
• Bars go in the context-window hover when that ring exists; otherwise a compact percent next to send
• Does not mix quota into the context-window ring number

Settings

Chat hover

[cursor]

Codex partials mislabeled as weekly

Medium Severity

Live Codex account.rate-limits.updated payloads reuse the full-snapshot resolver, which treats a lone duration-less primary window as weekly. Codex notifications are documented as partial, and mergeUsageLimitWindows upserts by kind, so a session-only patch can overwrite the weekly bar and leave the session bar stale during a turn.

Additional Locations (2)

• apps/server/src/provider/runtimeUsageLimits.ts#L129-L160
• apps/server/src/provider/providerUsageLimits.ts#L104-L126

 

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

[derektrimm]

We hit a few landmines building the usage-limits implementation in #5739 that this PR's data paths will also cross, so passing them along to save the rediscovery:

1. Claude reports utilization in two units, 100x apart. The streamed rate-limit events (and the anthropic-ratelimit-unified-*-utilization response headers they are built from) are a 0-1 fraction; GET /api/oauth/usage is 0-100. I verified this directly: hitting /v1/messages with a Claude Code OAuth token and calling the usage endpoint in the same second gave header 7d-utilization: 0.11 vs endpoint "seven_day": { "utilization": 12.0 }. Since this PR refreshes usageLimits from live session events on top of probe-populated snapshots, merging event values without scaling renders the binding window ~100x too small. This exact bug shipped on our branch and was caught by a user in the wild (see the report from Moinax in the feat(usage): show 5h/weekly rate limits on the usage page and sidebar hover #5739 thread). Worth confirming which unit the scraped /usage output uses before mixing the two sources.

2. A streamed rate-limit event only names the currently binding window, never the full set. If the event-driven refresh replaces the snapshot's window list rather than merging by window key, every non-binding window (weekly, model-scoped) vanishes until the next full probe. We ended up pulling the full set separately (throttled) for this reason.

3. Limits belong to the account, not the provider type. Two Claude provider instances signed into different accounts have independent windows; keying the cache or snapshot by provider type makes one account's numbers silently overwrite the other's. That was the whole of fix(usage): attribute account limits per provider instance #7133 on our branch.

4. Treat the window set as data, not schema. Codex has shipped and then paused its 5-hour window, and Claude adds model-scoped weeklies (e.g. a "Fable"-scoped window) that come and go. Hardcoding the expected windows per provider breaks silently when the set changes upstream.

Happy to share the test fixtures we built for these cases if useful.

[macroscopeapp]

One finding in the in-scope web files: an empty provider tile can render when a usage snapshot decodes as available with zero windows. Everything else (bar geometry/role="progressbar"/motion-reduce matching ContextWindowMeter, locale-consistent reset formatting via timestampFormat.ts, indicatorBackground matching the page surface) is consistent with the existing system.

^{Posted via Macroscope — UI Consistency}

[cursor]

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

There are 32 total unresolved issues (including 31 from previous reviews).

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

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

[cursor]

Monthly windows classified as weekly

Medium Severity

windowKindFromDuration treats a window as monthly only when duration is strictly greater than 30 days. Codex Free/Go and Cursor both stamp exactly 30 days (43200 minutes), so those windows classify as weekly. Codex then labels the bar Weekly instead of Monthly.

Additional Locations (1)

• apps/server/src/provider/codexUsageProbe.ts#L12-L13

 

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

[Aditya190803]

Quick update:

1. Fixed the reset dates, which were previously only shown for the week. They’re now shown separately for both session and week.
2. For those who wanted usage displayed in the chat box, check out this PR: #8445

I wanted to make this a stacked PR, but couldn’t get that working, so I opened a new PR instead. I didn’t close this one since quite a few people are already following it.

[Aditya190803]

It is a Opt in Feature

[derektrimm]

Thanks for the update, and for how much of the earlier list you've taken on - I went back through the current diff (plus the pipeline copy in #8445) and most of it is genuinely handled now. Wanted to close the loop properly:

1. Unit scaling - handled for the streamed events, and the tests covering both directions are much appreciated. One small heads-up for the future: the <= 1 check is a magnitude heuristic rather than a typed unit, so a genuine sub-1 percent value (0.4% early in a fresh window) would render as 40%, and utilization: 1 is technically ambiguous (100% on the fraction scale, 1% on the percent scale). Since the OAuth endpoint and rate-limit headers aren't ingested yet, this can't bite today - but if a later change adds them, this seam is where the 100x bug would sneak back in. A short comment noting the ambiguity is probably all it needs for now.

2. Merge vs replace - this is handled really well. The upsert semantics, carrying sparse fields forward, the per-window epochs guarding against a slow probe reverting a live patch, and the unavailable-probe protection are all exactly the shape we wished we'd built the first time. Nice work.

3. Per-instance keying - handled. Ingestion routes by providerInstanceId into the instance's own snapshot, and the UI keys by instanceId everywhere I looked. Two same-type accounts can't cross-contaminate.

4. Window set as data - this is the one I'd still love to see before merge, and the code is already halfway there: the renderers are fully data-driven (windows.map), so only the contract and merge key need to open up. Right now kind is a closed enum and mergeUsageLimitWindows keys its Map on kind, so two real windows of the same kind can never coexist - the comment on CLAUDE_WINDOW_BY_RATE_LIMIT_TYPE says it best ("would all collapse onto the same 'weekly' slot and fight over it"). That means model-scoped weeklies stay invisible, and any future window under 7 days gets labeled "session" and collides with the real one. A possible shape: give each window an opaque stable key (the provider's own identifier, e.g. the rate_limit_type string, falling back to label), merge on that key, and derive display order from windowDurationMins. Then provider window changes become a data change instead of a code change.

One perf observation on the #8445 copy of the pipeline, offered in the spirit of this repo's performance bar: every account.rate-limits.updated event currently republishes the full ServerProvider snapshot (models, skills, slash commands) to every connected client, and the dedupe guard in applyUsageLimits never gets a chance to fire - applyRuntimeUsageLimits stamps a fresh checkedAt on every event, so the value always differs even when every percentage is identical. Comparing just the window fields and keeping the previous checkedAt when nothing changed would make no-op events free on the wire.

Happy to share our test fixtures for the same-kind-window and unit-mismatch cases if they'd save you time - and thanks again for pushing this feature forward, a lot of people clearly want it.

[Guitaraholic]

Hi — first contribution here. Julius already picked this PR as the place for provider limits, so I worked against this thread rather than opening another one. I did a final pass to drop unused helpers and duplicated cache-key wiring so the diff stays only the behaviour below.

This pass is meant to clear the remaining review items on this PR and to bring over the probe hygiene from the closed subscription-limits work in #8327, without taking that PR’s separate ingest or UI. Theo’s must-fix there was Claude /api/oauth/usage 429s: reuse a successful read for 180 seconds, and if a probe fails (429, missing binary, timeout, old CLI) back off for 10 minutes instead of spawning again on every health tick.

Fixes

• Quota windows now have a stable provider key, so same-kind bars (weekly all-models vs Fable / Opus / Sonnet) no longer collapse.
• Identical rate-limit events no longer republish the full provider snapshot.
• 30-day windows classify as monthly.
• A skipped probe keeps the last published snapshot, including Grok’s honest unavailable reason.

Additions

• That 180s / 10-minute cache on Claude, Cursor, Grok /usage, and Codex account/rateLimits/read, keyed per account.
• Codex durations use the TUI ±5% bands; missing durations are labelled Usage / Secondary instead of guessing 5h vs weekly from position.
• A Token cost heading under Provider limits so the transcript chart is not a continuation of the quota bars.

OpenCode is a router over BYO keys, so it is not shown as a subscription meter. Composer/thread meters stay on the stacked follow-up (#8445).

Happy to adjust anything that still doesn’t match what you wanted on this PR.

I don’t have push access to this PR’s head branch, so the commits are on Guitaraholic/t3code@local/usage-limits (compare against this PR). Happy for you to pull them onto this branch.

[juliusmarminge]

Superseded by #9507, which landed the usage Limits tab (distilled from this PR's server model / provider snapshot approach). Closing as superseded — thank you @Aditya190803.