burn limits: quota-window tracking across providers

[willwashburn]

Why

Spend has two axes: dollars and quota consumption. Many users are on Claude Pro/Max plans where hitting the 5-hour wall matters more than the dollar total. Burn today reports only $; adding quota windows completes the picture and directly serves the meta-goal of "is my current harness/model choice efficient?"

Endpoints

Reverse-engineered by TokenTracker — see their src/lib/usage-limits.js:55-588. Reusing, not re-deriving.

Provider	Endpoint / method	Auth	Returns
Claude	GET https://api.anthropic.com/api/oauth/usage	OAuth token from Claude Code state	five_hour, seven_day, seven_day_opus, extra_usage — each with percent_used, reset_at
Codex	GET https://chatgpt.com/backend-api/wham/usage	ChatGPT session	primary_window, secondary_window (Auto / API lanes)
Cursor	SQLite auth extract + CSV fetch	State DB	plan.totalPercentUsed, on-demand cents
Gemini	Per-model remaining-token budget endpoint	API key	Remaining-fraction per model

MVP scope

Claude only in this issue. File follow-ups for Codex / Cursor / Gemini when those readers land (currently Codex is scaffolded, others deferred).

CLI

burn limits                # one-shot snapshot
burn limits --watch [5s]   # refresh loop, default 5s interval
burn limits --json         # programmatic

Output shape (TTY):

Claude
  5-hour      34% used  resets in 2h 14m
  7-day       12% used  resets in 4d 6h
  7-day Opus   8% used  resets in 4d 6h

Constraints

• Don't log or persist OAuth tokens; read from Claude Code's existing state on each invocation.
• Cache responses for ≤ 30s in-process to support --watch without hammering the endpoint.
• If the OAuth token is absent or expired, print one clear line explaining where it should be and how to refresh — no stack trace.
• No background daemon. burn limits is a foreground command.

Acceptance

• burn limits prints Claude's 5-hour and 7-day windows with correct percent-used and a human-friendly time-to-reset.
• --watch refreshes in-place without flicker and exits cleanly on Ctrl-C.
• Token-missing case produces a one-line actionable message, exit code 2.
• Unit test mocks the endpoint and asserts parsing + formatting for each window type.

Depends on

Nothing. Independent of #1 / #2 / #3.

[willwashburn]

Scope expansion from ccusage: add usage-derived forecasting as a complement to the OAuth-endpoint path this issue currently specs.

Why both paths matter

The OAuth endpoint (https://api.anthropic.com/api/oauth/usage) is authoritative but static — it returns percent-used at a point in time. It cannot answer "at current rate, will I hit the wall before my next reset?" because it doesn't expose per-turn consumption within the window.

Ccusage's apps/ccusage/src/_session-blocks.ts:295-321 (projectBlockUsage()) computes the forecast from local data:

burnRate.tokensPerMinute = (totalTokensSoFar) / (minutesSinceBlockStart)
remainingMinutes = blockEndTime - now
projectedAdditionalTokens = burnRate.tokensPerMinute × remainingMinutes
projectedBlockTotal = actualSoFar + projectedAdditionalTokens

Turns the output from "you're at 34%" into "you're at 34%, on pace for 87% by reset." Actionable — matches the meta-goal of "switch to Haiku now to extend runway by 2h."

The 5-hour window is hardcoded in ccusage (_session-blocks.ts:8: DEFAULT_SESSION_DURATION_HOURS = 5), inferred from Anthropic's public billing docs, not learned from the API. Means forecasting works offline, no OAuth dependency.

Revised CLI

burn limits                       # OAuth snapshot + local forecast combined
burn limits --no-forecast         # OAuth only
burn limits --no-api              # local forecast only (offline)
burn limits --watch [5s]          # refresh both
burn limits --json                # programmatic

Output shape (TTY):

Claude
  5-hour window:
    OAuth:     34% used     resets in 2h 14m
    Forecast:  87% projected at block-end (burn rate 3.2k tok/min)
    Advice:    on pace to hit the wall; switch tier to extend

  7-day window:
    OAuth:     12% used     resets in 4d 6h

When OAuth and forecast disagree substantially, surface both without reconciling — they measure different things (actual vs. projected).

Forecast math needs ledger data

The forecast requires per-turn usage within the current 5-hour window, which comes from the burn ledger. So this extension doesn't add a network dependency — just leverages data we already collect.

Gap blocks (optional polish)

Ccusage's isGap concept (_session-blocks.ts:128-133, 216-246) inserts synthetic blocks when the gap between two entries exceeds the session duration. Nice UX in a historical burn blocks view, not load-bearing for the primary forecast. Nice-to-have, not must-have.

Acceptance addition

• burn limits displays both the OAuth-reported percent-used AND a locally-computed forecast (when recent data exists in the ledger).
• Burn rate calculated from turns with ts inside the current 5-hour window.
• If the ledger has no turns in the active window, forecast degrades gracefully to "insufficient data."
• --no-api mode works fully offline when OAuth token is unavailable or expired.

[BossChaos]

🎯 Claiming this issue!

I've implemented the burn limits command with full quota tracking:

Features:

• ✅ burn limits - One-shot snapshot of all Claude quota windows
• ✅ burn limits --watch [5s] - Real-time monitoring with configurable refresh
• ✅ burn limits --json - Programmatic JSON output for integrations

Tracks:

• 5-hour window (usage % + reset countdown)
• 7-day window (usage % + reset countdown)
• 7-day Opus window (usage % + reset countdown)
• Extra quota (usage % + reset countdown)

Implementation:

• Reads OAuth token from ~/.claude/state.json
• Calls GET https://api.anthropic.com/api/oauth/usage endpoint
• Clean CLI output with color-coded usage bars

PR submitted: #45

Ready for review! 🚀