[FEATURE] Expose rate-limit / plan quota usage in statusLine JSON input

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

Claude Code's statusLine lets users build custom terminal HUDs via a shell script that receives session JSON on stdin. Today that JSON includes context_window, cost, model, and workspace — but zero information about plan-level rate limits (the 5-hour session %, weekly all-models %, weekly Sonnet-only % shown in /usage and on claude.ai > Settings > Usage).

The result: users get rate-limited mid-session with no warning. The only way to check quota is to break flow and open a browser or run /usage manually (which can't be called programmatically or from hooks/scripts).

This is the single most duplicated feature request on this repo — at least 15 separate issues filed, 30+ upvotes on the top one, multiple community workarounds built, and users have even reverse-engineered an undocumented OAuth endpoint to get this data. The demand is overwhelming and the data already exists internally.

Proposed Solution

Add a rate_limits object to the statusLine JSON input. Minimal viable spec:

{
  "rate_limits": {
    "session": {
      "used_percentage": 42,
      "resets_at": "2026-02-23T18:00:00Z"
    },
    "weekly": {
      "used_percentage": 67,
      "resets_at": "2026-02-27T08:00:00Z"
    },
    "weekly_sonnet": {
      "used_percentage": 15,
      "resets_at": "2026-02-27T19:00:00Z"
    }
  }
}

That's it. Three objects, two fields each. No breaking changes — existing scripts that don't read rate_limits are unaffected.

Why this is low-effort to implement

The data is already available in multiple places:

1. API response headers — every API call returns anthropic-ratelimit-unified-status and anthropic-ratelimit-unified-reset headers. Claude Code already parses these to power the /usage command.
2. /usage command — already displays this exact data in the TUI. It just needs to be forwarded to the statusLine JSON.
3. Undocumented OAuth endpoint — GET https://api.anthropic.com/api/oauth/usage returns { "five_hour": { "utilization": 42.0, "resets_at": "..." }, "seven_day": { ... } } (discovered by community in #13585).

The implementation is essentially: take the data /usage already has → serialize it into the statusLine JSON payload. No new API calls, no new backend work.

Alternative Solutions

| Workaround | Why it fails |
|---|---|
| Manually run /usage | Can't be called from scripts/hooks, interrupts flow, not persistent |
| Check claude.ai/settings/usage in browser | Context switch, breaks flow, defeats purpose of CLI |
| Track cost.total_cost_usd | Doesn't map to quota % — plans don't express limits in dollars |
| Community tools (claude-rate-monitor, claude-code-limit-tracker) | Fragile hacks, inaccurate, require extracting OAuth tokens from OS keychain |
| Scraping claude.ai via browser automation | Platform-specific, fragile, slow |

None of these are real solutions. The data needs to come from Claude Code itself.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

1. I start a Claude Code Opus session for a complex refactor
2. My status line shows: ⬥ Opus 4.6 │ ██████░░░░ 42% ctx │ $0.47 │ ⚡Session: 73% │ 📅Week: 45%
3. I see session quota at 73% — I know I have roughly 1 more intensive session before the 5-hour window resets
4. I finish the critical work on Opus, then switch to Sonnet for routine tasks
5. I never get surprise rate-limited. I never leave the terminal.

Without this feature, step 2 shows nothing about quota, and step 3 is replaced by "suddenly get rate-limited, lose momentum, open browser to find out why."

Additional Context

Current statusLine JSON (captured via debug script on v2.1.47)

{
  "session_id": "...",
  "model": { "id": "claude-opus-4-6", "display_name": "Opus 4.6" },
  "cost": { "total_cost_usd": 0.477 },
  "context_window": {
    "used_percentage": 20,
    "remaining_percentage": 80,
    "context_window_size": 200000,
    "current_usage": { "input_tokens": 1, "output_tokens": 147 },
    "total_input_tokens": 7104,
    "total_output_tokens": 5237
  },
  "workspace": { "current_dir": "..." },
  "version": "2.1.47"
}

Note the complete absence of any rate-limit or quota fields.

Consolidated duplicate issues

This request consolidates the following issues — all asking for the same thing in different words:

| # | Issue | Upvotes | Status |
|---|---|---|---|
| 1 | #5621 — StatusLine should expose API usage/quota in JSON input | — | Closed (not planned) |
| 2 | #6093 — Native status line for 5h and weekly limits | — | Closed (duplicate) |
| 3 | #10527 — Display usage statistics in CLI terminal | — | Closed (duplicate) |
| 4 | #11917 — Expose usage metrics in session JSON | — | Open (stale) |
| 5 | #13585 — Add quota information access to CLI | — | Open |
| 6 | #13667 — Display Max/Pro rate limits in status line | — | Closed (duplicate) |
| 7 | #14136 — Expose plan usage/subscription limits in status line | 7 | Open |
| 8 | #15844 — Expose usage quota in status line JSON | 13 | Open |
| 9 | #18121 — Expose rate limit/session usage to statusLine | — | Open |
| 10 | #19385 — Expose rate limit data in statusline JSON input | — | Closed (duplicate) |
| 11 | #20636 — Expose rate limit usage (session %, weekly %) to statusLine | 31 | Open |
| 12 | #22221 — Expose Max/Pro plan usage limits for status line display | — | Open |
| 13 | #23650 — Show plan usage allowance in status bar | — | Open |

Combined community signal: 50+ upvotes, 15+ issues, 3+ community workaround tools built.

The question isn't whether users want this — it's the most requested statusLine feature by far. The question is just when it ships.