Expose rate-limit utilization headers in session data or CLI
Problem
Claude Code receives anthropic-ratelimit-unified-5h-utilization and anthropic-ratelimit-unified-7d-utilization headers on every API response — the same data Claude Desktop uses to render its usage bar. However, this data is not persisted anywhere accessible to external tooling:
Not in the session JSONL files (~/.claude/projects/*/)
Not in stats-cache.json
Not queryable via any CLI command
Not exposed through hooks
This makes it impossible for third-party tools (system tray widgets, monitoring dashboards, team usage trackers) to show accurate usage percentages. The only workaround is summing tokens from JSONL files against a manually-configured guess of the quota limit — which is unreliable since the actual limits aren't documented.
Proposed Solutions (any one would help)
Persist utilization in JSONL — Include the unified-5h-utilization and unified-7d-utilization values alongside message.usage in the session JSONL entries.
CLI command — e.g. claude usage or extend /cost to output the current 5h and 7d utilization percentages from the most recent API response.
Expose via OpenTelemetry — Add the utilization values as metric attributes when OTEL is enabled.
Use Case
I built a small floating desktop widget that reads Claude Code's JSONL files to show token consumption in the Windows taskbar. It works, but the percentages are approximations because:
The real quota limits for Max/Pro plans aren't published
Token counting from JSONL doesn't account for server-side weighting (peak vs off-peak, model differences, etc.)
Having access to the actual utilization values would make this — and any similar monitoring tool — accurate.
Environment
Claude Code on Windows 11
Claude Max $100/mo plan
Python widget reading from ~/.claude/projects/
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗