[FEATURE] Expose rate limit utilization data in status line JSON
Problem Statement
The status line feature (statusLine in settings.json) is an excellent customization point, but it's missing critical data that Claude Code already has access to internally: rate limit utilization.
Claude Code already reads the anthropic-ratelimit-unified-* HTTP response headers from the API on every request:
anthropic-ratelimit-unified-*-utilization— current usage percentageanthropic-ratelimit-unified-*-reset— when the window resetsanthropic-ratelimit-unified-*-surpassed-threshold— threshold crossed (e.g. 75%, 80%)anthropic-ratelimit-unified-status—allowed/allowed_warning/rejectedanthropic-ratelimit-unified-overage-status— whether extra usage is activeanthropic-ratelimit-unified-representative-claim— the rate limit type/window
This data is parsed internally into fields like utilization, rateLimitType, isUsingOverage, surpassedThreshold, and resetsAt, but none of it is included in the JSON that gets piped to status line scripts via stdin.
For Max subscribers ($100/$200/mo plans), the cost.total_cost_usd field is essentially meaningless since usage is subscription-based with rolling windows, not pay-per-token. The only useful metric for these users is their actual utilization percentage against their plan limits — which Claude Code already knows but doesn't expose.
Proposed Solution
Add the following fields to the status line JSON input:
{
"rate_limit": {
"utilization": 0.45,
"status": "allowed",
"resets_at": 1709234567,
"rate_limit_type": "rolling_5h",
"is_using_overage": false,
"surpassed_threshold": null,
"overage_status": null
}
}
This would allow status line scripts to display actual plan utilization — e.g. a progress bar showing "45% of 5h window used" with color-coded warnings at thresholds, without any guesswork.
Alternative Solutions
- Self-tracking tokens across sessions: I built a persistent usage log that tracks tokens across sessions and displays rolling 5h/daily/weekly totals. It works but can't show actual plan utilization percentages — only raw token counts, which don't map to plan limits since the limits aren't publicly documented in token terms.
- Making a separate API call from the script: Not viable because it would consume tokens/quota just to check the quota.
- Reading HTTP response headers directly: The status line script runs after each message, but has no access to the HTTP response headers from the API call that just completed.
Use Case Example
- I'm on Claude Max 20x ($200/mo) using Claude Code heavily
- I've built a custom 7-line status line dashboard showing context, git, tokens, system health
- I want to see "5h window: 45% used" with a progress bar that turns yellow at 75% and red at 90%
- Currently impossible because the utilization data exists inside Claude Code's runtime but isn't passed to the status line script
- With this feature, I could show real plan usage alongside context usage, making the status line a true workstation dashboard
Additional Context
The internal code already parses these headers and maintains the state — this feature request is purely about including the already-parsed data in the JSON blob that gets piped to status line commands. Should be a small change since the data structures already exist.
Relevant internal fields found in the binary: rateLimitType, utilization, unifiedRateLimitFallbackAvailable, isUsingOverage, surpassedThreshold, overageStatus, overageResetsAt, overageDisabledReason.
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗