[FEATURE] Expose rate limits in --output-format json (--print mode)
Problem Statement
I run a batch automation script that resolves multiple tickets sequentially using claude -p --output-format json. Between each ticket, the script needs to decide whether to continue, pause until the hourly reset, or stop entirely to preserve weekly quota for interactive work.
Today the script is blind to rate limits — it can only detect failures reactively. There is no way to read rate limit data outside of interactive mode.
Proposed Solution
Add a rate_limits field to the --output-format json output, reusing the same data already exposed to the statusline:
{
"type": "result",
"result": "...",
"total_cost_usd": 0.42,
"rate_limits": {
"five_hour": {
"used_percentage": 45,
"resets_at": 1774112400
},
"seven_day": {
"used_percentage": 30,
"resets_at": 1774540800
}
}
}
The CLI already parses these values from API response headers (anthropic-ratelimit-unified-5h-utilization, anthropic-ratelimit-unified-7d-utilization) and passes them to the statusline. This would just expose the same data in the JSON output.
Alternative Solutions
- Reading the statusline JSON via a side-channel (temp file), but the statusline doesn't run in
--printmode - Making a raw API call to read rate limit headers, but this doesn't work with OAuth/Max authentication
- Detecting rate limit errors reactively after they happen (current workaround — wasteful and fragile)
Use Case Example
- I run
batch-resolve.sh 101 102 103 104 105to resolve 5 tickets sequentially - After each
claude -p "/resolve #N" --output-format json, the script readsrate_limitsfrom the JSON output - If
five_hour.used_percentage > 70%→ sleep untilfive_hour.resets_at - If weekly daily budget exceeded → stop the batch to preserve quota for interactive work
- Otherwise → continue to next ticket
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗