Expose model-scoped rate limits and extra_usage in the statusLine JSON payload

Claude Code already tracks model-scoped weekly limits and subscription overage credits internally, but the statusLine stdin payload projects only two of them, so statusline authors cannot surface the numbers that actually decide whether a session can continue.

What is available internally

Rate limit state is parsed from the anthropic-ratelimit-unified-* response headers and from the OAuth usage endpoint into these keys:

• five_hour
• seven_day
• seven_day_opus (labelled "Opus limit" in the UI)
• seven_day_sonnet (labelled "Sonnet limit")
• seven_day_overage_included (labelled "Fable 5 limit")
• extra_usage (is_enabled, monthly_limit, used_credits, utilization)

/usage renders these, and the SDK control-request payload receives a model_scoped projection of them.

Where it narrows

The statusLine payload builder discards everything except two keys (v2.1.220):

k = {
  ...w.five_hour && { five_hour: { used_percentage: w.five_hour.utilization * 100, resets_at: w.five_hour.resets_at } },
  ...w.seven_day && { seven_day: { used_percentage: w.seven_day.utilization * 100, resets_at: w.seven_day.resets_at } }
}
// ...
...(k.five_hour || k.seven_day) && { rate_limits: k }

The values are held in memory and never persisted, so there is no file a statusline script can read instead.

User-facing impact

On a Max plan the weekly Opus limit is routinely the binding constraint, and it is invisible from the statusline. Someone can see 7d 45% and reasonably start a large Opus task, then get cut off because the Opus-specific weekly limit was at 95%. The aggregate number does not predict that, so the statusline actively misleads at the moment the information matters most.

The same applies to extra_usage: users on overage credits cannot see how much of the monthly credit allowance is left without interrupting their work to run /usage.

Proposed change

Widen the projection to pass through the keys that are already populated, keeping the existing used_percentage and resets_at shape:

"rate_limits": {
  "five_hour":                  { "used_percentage": 12.4, "resets_at": 1753900000 },
  "seven_day":                  { "used_percentage": 45.9, "resets_at": 1754100000 },
  "seven_day_opus":             { "used_percentage": 95.1, "resets_at": 1754100000 },
  "seven_day_sonnet":           { "used_percentage": 31.0, "resets_at": 1754100000 },
  "seven_day_overage_included": { "used_percentage": 8.2,  "resets_at": 1754100000 },
  "extra_usage": {
    "is_enabled": true,
    "monthly_limit": 5000,
    "used_credits": 479,
    "utilization": 0.0958
  }
}

Every key stays optional, exactly as five_hour and seven_day are today, so existing statusline scripts are unaffected.

Current workaround, and why it is a poor one

The only way to get these values today is to read the OAuth token out of the macOS Keychain and call api.anthropic.com/api/oauth/usage directly from the statusline script. Several community statusline plugins do this. It puts a credential read and a network round trip on a hot path that runs on every render, and it depends on an undocumented endpoint. Since Claude Code already has the data in memory at the moment it builds the payload, passing it through removes the incentive for statuslines to handle OAuth tokens at all.

Related

• #80725 requests a remaining prepaid credit balance for API-credit accounts. That is a different billing mode than extra_usage here, but the two would sit naturally in the same part of the payload.

Environment

• Claude Code 2.1.220 (macOS, x86_64)