[Feature Request] Expose rate limit utilization data in statusLine JSON input

Resolved 💬 3 comments Opened Mar 19, 2026 by br3nt Closed Mar 22, 2026

Bug Description
Title: Expose rate limit utilization data in statusLine JSON input

Summary: I want to build a Mac menu bar widget (via xbar/SwiftBar) that displays my Claude Code usage — specifically the 5-hour session utilization %, weekly utilization %, and reset times. This would let me monitor my usage at a glance without running /usage inside a session.

Why this isn't currently possible:

  1. Rate limit data is response-header-only — The anthropic-ratelimit-unified-* headers (status, utilization, reset, representative-claim) are only returned on API responses and held in-memory. They are not persisted to disk or exposed to any extension point.
  2. OAuth tokens can't call the API directly — The OAuth access token from the macOS keychain (Claude Code-credentials) is rejected with "OAuth authentication is currently not supported" when used against /v1/messages or /v1/messages/count_tokens. Claude Code routes through an internal mechanism we can't

replicate.

  1. Hooks don't receive rate limit data — Notification, Stop, PreToolUse, PostToolUse hooks receive context about the event but not the current rate limit state.
  2. StatusLine doesn't include it — The statusLine JSON input includes cost, context_window, model, and workspace — but not rate limit utilization or reset times.
  3. Local session metadata is insufficient — ~/.claude/usage-data/session-meta/*.json contains per-session token counts but not the server-side utilization percentages or limits needed to calculate usage ratios.

Suggested solutions (any one would unblock this):

  • Option A (simplest): Add rate_limit to the statusLine JSON input: { "rate_limit": { "status": "allowed", "utilization": 42, "resets_at": 1773900000, "rate_limit_type": "five_hour" } }. The statusLine command already runs on every state change, so this is zero additional API cost.
  • Option B: Add a RateLimitChange hook event that fires when yvq() updates the rate limit state, passing the full rate limit info as hook input JSON.
  • Option C: Expose a claude usage --json CLI command that outputs the last-known rate limit state from the most recent session, or queries the API for current utilization.
  • Option D: Persist rate limit state to ~/.claude/rate-limit.json on every update, so external tools can read it.

Environment Info

  • Platform: darwin
  • Terminal: iTerm.app
  • Version: 2.1.79
  • Feedback ID: 3700536b-21ee-409e-8fa0-39dfd89cf277

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗