[FEATURE] Compare plans: replay my usage against each plan's 5h and weekly windows
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] This is a single feature request (not multiple features)
Problem Statement
I can't tell whether I'm on the right plan, and I don't think it's currently possible to find out.
/usage shows me where I stand right now — session cost, plan limits, activity stats. Settings > Usage shows progress bars for my 5-hour and weekly windows. Neither answers the question I actually have, which is whether the plan I'm paying for is the plan I need.
The question is hard for three reasons, and they compound:
- Plan fit is decided by windows, not monthly totals. Quota is metered in a rolling 5-hour session window, a weekly all-model window, and (on Max) at least one additional model-specific weekly window. So "my usage costs $X/month at API rates, and Max 20x costs $Y, therefore Max 20x is fine" is invalid reasoning — it ignores when the tokens landed. Two people with identical monthly token totals can have completely different experiences: one who works evenly across the week fits Pro; one who does four-hour Opus marathons on Tuesdays does not fit Max 5x. Nothing exposes this.
- My quota is filled by every surface, not just Claude Code. Per the usage credits documentation: "Usage credits apply to both Claude conversations and Claude Code terminal usage. Your combined usage across both interfaces counts toward your limits." Add Cowork, Claude in Chrome, Claude in Excel, mobile, and Research mode. When my 5-hour window fills, I have no idea which surface filled it. I can't even see the split.
- What a full window costs depends on a setting most people don't think about. With usage credits disabled, hitting a ceiling costs me time — I'm blocked until reset. With credits enabled, the same ceiling costs me money — overflow bills at standard API rates. With credits enabled but a monthly cap that binds, or a prepaid balance that empties, I'm blocked anyway, without warning. Three different currencies — hours, dollars, refused requests — and nothing converts between them.
The consequence shows up in this tracker as a steady stream of billing confusion that nobody, including triage, can resolve:
#75518 — $115 charged on Max while the weekly quota bar sat at 73%. (Currently labeled question, which suggests triage already suspects this may be plan mechanics rather than a fault.)
#75661 — credits depleted without proper usage accounting when exceeding the monthly max
#75757 — subagents billed after the monthly spend limit was exceeded
#73615 — cost reporting discrepancy between session display and billing
#75518 is the instructive one, because it may not be a bug at all. A weekly bar at 73% and a real $115 charge are not contradictory: the 5-hour window can be exhausted repeatedly inside a week that never fills its weekly bucket, and each exhaustion spills into credits. The bar shows one meter; the charge comes from another.
Or it is a bug. The point is that neither the reporter nor whoever triages it can currently tell. Users have no way to model what their usage should have cost, so they cannot distinguish "I was billed incorrectly" from "I did not understand how my plan meters." That ambiguity is the problem I want solved.
Proposed Solution
A "Compare plans" view in Settings > Usage that replays my actual account usage against each plan's real ceilings and tells me, for each plan, what that plan would have cost me — in both currencies.
Concretely: take the calls I actually made, with their timestamps, models, and token counts. Replay them against Pro, Max 5x, and Max 20x, simulating each plan's rolling 5-hour and weekly windows. For every plan, report where I would have hit a ceiling, and what hitting it would have meant.
Compare plans · usage from 2026-04-10 → 2026-07-09
4,238 calls · 312 sessions · Claude Code 68% · chat 24% · Cowork 8%
Peak 5h window Tue 2026-05-19 14:00 Peak week 2026-06-01 (2.9x median)
── credits OFF ── ── credits ON ──
Plan Base 5h hits blocked overflow total/mo
─────────────────────────────────────────────────────────────
Pro $20 94 61.5h $1,712 $1,732
Max 5x $100 23 14.0h $394 $494
Max 20x $200 2 1.5h $31 $231
API only — — — $1,847 $1,847
You are on Max 20x, credits ON, $30/mo cap.
Actual: $200 + $31 overflow = $231/mo
Your $30 cap bound in week 9. 4 requests were refused.
→ Max 5x + credits would save $37/mo and cost ~14h of interruption.
→ 2 of your 3 ceiling hits were one Opus refactor on 2026-06-03.(Figures are illustrative, not from my account.)
What makes this work, and what makes it different from a cost report:
It simulates rolling windows, not months. A plan "fits" if I never hit a ceiling — not if the monthly arithmetic happens to work out.
It prices both failure modes side by side. Blocked hours when credits are off; overflow dollars when they're on. Nobody should have to guess whether $37/month is worth 14 hours of interruption. Show the number; let me decide.
It models the spend cap and prepaid balance. A simulation that assumes credits always rescue you overstates how smoothly they do. When the cap binds, requests are refused — and that third failure mode is invisible today.
It breaks consumption down by surface. The single most useful line for anyone trying to understand their own usage, and the one thing no local tool can produce.
It attributes ceiling hits to specific work. "Both hits were one Opus refactor on June 3rd" is actionable. "94% of quota consumed" is not.
This has to live server-side, at the account level. That is not an implementation preference; it's a correctness requirement. The server is the only place that has all surfaces' consumption, the authoritative ceiling values, my account's assigned weekly reset offset, and the ground truth of which calls billed against quota versus credits.
Alternative Solutions
- ccusage and similar local log parsers. ccusage parses ~/.claude/projects/*.jsonl and produces daily, monthly, and per-session cost breakdowns, pricing tokens against LiteLLM's community pricing mirror. It's genuinely good and it's what I use today. It cannot answer this question, for three reasons:
The local logs contain Claude Code usage only. Replaying them against plan windows would silently omit my chat, Cowork, and Chrome consumption. It would tell me "Pro fits" while ignoring the sessions that actually exhausted my window. For a tool whose purpose is answering am I on the right plan, that isn't a rounding error — it's a wrong answer delivered as a confident table.
The ceilings aren't public. The 5-hour window's capacity, the weekly ceilings, how Opus is weighted against a shared budget, and the structure of Max's model-specific weekly limit are not documented precisely enough to simulate against. Public sources even conflict on whether Max's second weekly limit is Opus-scoped or Sonnet-scoped. ccusage is inferring the walls from where users report bouncing off them.
Weekly windows reset at an account-assigned time. The client doesn't know that offset, and getting it wrong shifts every weekly bucket boundary.
- #50926 — "Expose /cost and /usage data programmatically to hooks and plugins" (open). This is the closest live request, and I want to be clear it is complementary, not equivalent. #50926 asks for session-level, client-side data to be made machine-readable. My central claim is that session-level client-side data is structurally insufficient for plan comparison, because it sees one surface out of many.
Granting #50926 in full would still leave this question unanswerable. Worse, granting it without an account-level aggregate would let third-party tools produce confident, wrong plan recommendations from partial data — which is arguably worse than the status quo. Both should happen. That's the part I'd most like a maintainer to engage with.
- #42607 — "Add token and cost transparency to Claude Code CLI" (closed as not planned; #72663 was auto-closed into it). That request was for display of what a session cost. This is a request for simulation of what a session would have cost under a different plan. Different question, different machinery.
- Just upgrade, wait a month, and see. This is what I currently do. It costs a month and a plan differential per data point, and it doesn't isolate variables — my usage next month won't match last month's. It also can't answer "would the cheaper plan have worked?", because once you're on the cheaper plan and blocked, you've already lost the time.
- Read the docs and estimate by hand. Not possible; see the ceilings point above.
Priority
Medium - Would be very helpful
Feature Category
Other
Use Case Example
Scenario: deciding whether to downgrade from Max 20x.
I'm on Max 20x at $200/month with usage credits enabled and a $30/month cap. I've been on it for a quarter. It feels like more plan than I need, but I have no way to check, and the downside of guessing wrong is being blocked mid-sprint.
I open Settings > Usage → Compare plans and select the last 90 days.
The view shows me that Claude Code was 68% of my consumption, chat 24%, Cowork 8%. I had not realized chat was a quarter of my quota — I'd been reasoning entirely from /usage in the terminal, which sees two-thirds of the picture.
It shows Max 5x would have hit the 5-hour ceiling 23 times over 90 days. With credits enabled, that's about $394 of overflow — total $494/month, versus my current $231. Downgrading would cost me more, not less. I would never have guessed that, and the monthly-total arithmetic implies the opposite.
It shows my $30 credit cap bound in week 9 and four requests were refused. I hadn't noticed. I raise the cap to $50.
It shows two of my three Max 20x ceiling hits came from a single Opus refactor on June 3rd. I keep the plan, but I now know to plan large Opus refactors at the start of a window rather than the end.
Total time: two minutes. Today this question is unanswerable at any price, and the four issues linked in the Problem Statement are what happens when people try to answer it anyway.
Additional Context
Why this can't be a client-side feature. Covered in Alternative Solutions, but to state the core plainly: ~/.claude/projects/*.jsonl contains Claude Code usage only, while quota is filled by every surface on the account. Any tool built on those logs — including a hypothetical claude usage --compare-plans — would systematically undercount and produce wrong plan recommendations. The aggregation has to happen where the data is aggregated.
Possible follow-ons, explicitly not part of this request. Noting them only so the shape is visible; I'd rather this ship narrow than not ship:
Surfacing the same computation in the CLI (/usage --compare-plans) as a view over the account-level result, not a local recomputation.
If the computation is reachable programmatically, #50926 is satisfied as a side effect — and satisfied correctly, with cross-surface data rather than a partial session-local view.
Related open issues. #75621 (usage credits indicator always shows USD regardless of billing currency) is effectively a prerequisite — a comparison table that mixes a EUR subscription price against USD overflow would be actively misleading. #70459 and #76147 (auto-compaction consuming far more quota than expected) describe an amplifier any correct simulation must model: compaction itself costs tokens, and can push you into a ceiling. #74796 (retry pricing transparency) is another. #70225 (enforce budget after mid-session subscription→API transition) overlaps on the credits-overflow case but concerns enforcement going forward, where this is accounting looking backward.
Caveats I'd want stated in the UI, not hidden:
Blocked hours is an estimate, not a measurement. It assumes I'd have waited for the reset rather than switching to Haiku or stopping for the day. It should be labeled an upper bound.
Historical prices and historical ceilings both drift. If Max's weekly ceiling moved 40 days into a 90-day lookback, the replay should use the ceiling that was actually in force, and say so. "What it would have cost" is the useful question for a plan decision; "what it would cost today" is a different one. The report should state which it answered.
Cache reads are frequently the largest token category and price very differently from fresh input. A comparison that charged them at full input rate would be worse than no comparison.
Two open questions I couldn't resolve from public documentation, both of which are themselves small evidence for the argument that this must be first-party:
Do Claude Code GitHub Actions runs and Agent SDK usage draw on subscription quota, or do they always require separate API billing? This materially changes the model for anyone running automation.
What is the exact structure of Max's model-specific weekly ceiling? Public sources conflict on whether it is Opus-scoped or Sonnet-scoped.
Scope guardrail. Read-only, always. No plan changes, no purchases, no adjusting auto-reload from this view. Report only.
On venue. I recognize this repo tracks the Claude Code CLI, and the surface I'm proposing is an account settings page — which is why I selected "Other" for category. I'm filing here because it's the public, triaged channel and because /usage is the natural secondary surface. Happy to move it if there's a better home.
On the business case. A view that tells someone "you're on the wrong plan, the cheaper one fits your usage" will sometimes cost Anthropic revenue. Shipping it anyway is a strong signal. The status quo — users reverse-engineering their bills with third-party log parsers, then filing issues alleging overcharges they can't substantiate and maintainers can't refute — is worse for everyone, margin included.