[FEATURE] Add API usage quota information to statusline JSON data

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

As a Claude Code user, I want to monitor my API usage quota directly in my terminal's status line, similar to what's shown in the Claude Code UI (Settings > Usage tab). Currently, the statusline command receives comprehensive session data (model info, context usage, cost), but lacks quota information:

• Current usage percentage (e.g., "19% used")
• Daily/monthly quota limits
• Reset time (e.g., "Resets 10pm Europe/Kiev")

This makes it impossible to:

1. Monitor how much quota I have left without opening the UI
2. Pace my usage throughout the day
3. Know when my quota resets
4. Create informed statusline displays that show real quota data

The UI already displays this information beautifully, but it's not accessible to statusline scripts, forcing users to either:

• Constantly switch to the UI to check usage
• Hardcode approximate limits (unreliable and inaccurate)
• Go without quota monitoring entirely

Proposed Solution

Extend the JSON data passed to statusline commands (via stdin) to include a quota object with usage information:

{
"hook_event_name": "Status",
"model": { "id": "claude-sonnet-4-5", "display_name": "Sonnet 4.5" },
"context_window": { ... },
"cost": { ... },

// NEW: Add quota information
"quota": {
"period": "daily", // or "monthly"
"current_usage": 146755, // tokens used in current period
"limit": 1000000, // total tokens available
"percentage_used": 14.67, // calculated percentage
"reset_time": "2025-12-25T22:00:00Z", // ISO 8601 timestamp
"reset_timezone": "Europe/Kiev", // user's timezone
"plan": "pro" // or "max", "team", etc.
}
}

Alternative Solutions

Ideal user experience:

1. User configures statusline script at ~/.claude/statusline-command.sh
2. Script receives quota data in JSON via stdin
3. Script parses and displays: "Claude Sonnet 4.5 | Context: 19% | Quota: 15%, reset 10pm"
4. User can monitor usage in real-time without leaving terminal

Example statusline script:
#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
QUOTA_PCT=$(echo "$input" | jq -r '.quota.percentage_used // "N/A"')
RESET_TIME=$(echo "$input" | jq -r '.quota.reset_time' | date -j -f "%Y-%m-%dT%H:%M:%SZ" "+%I%p" 2>/dev/null || echo "N/A")

echo "Claude $MODEL | Quota: ${QUOTA_PCT}%, reset ${RESET_TIME}"

---
Alternative Solutions:

Attempted workarounds:

1. Parse ~/.claude/stats-cache.json - Contains historical token usage but no quota limits or reset times
2. Hardcode limits based on plan - Unreliable, requires manual updates when plans change, doesn't account for actual backend limits
3. Make API calls to claude.ai - Not possible; no public API for quota, requires authentication, too slow for statusline updates
4. Read from session transcripts - Quota info not stored there

How other tools solve this:

• GitHub CLI (gh) shows rate limit info: gh api rate_limit
• Anthropic Console UI shows usage - but this data isn't exposed to CLI
• OpenAI CLI shows quota usage when available

Why current workarounds fail:
None of these approaches provide real-time, accurate quota data from the actual Claude backend. Only Claude Code has this information, but it's not exposed to statusline scripts.

---
Priority:

Medium-High - This significantly improves the developer experience by:

• Preventing unexpected quota exhaustion during long sessions
• Enabling better usage planning and pacing
• Matching the information richness of the UI in the CLI
• Supporting power users who prefer terminal-based workflows

---
Feature Category:

CLI & Developer Experience (specifically statusline/monitoring features)

---
Use Case Example:

Real-world scenario:

1. Morning work session (9am):

• I start Claude Code in my terminal
• My statusline shows: Claude Sonnet 4.5 | Context: 5% | Quota: 8%, reset 10pm
• I know I have 92% of my daily quota remaining

1. Heavy refactoring (2pm):

• Working on a large codebase migration
• Statusline updates: Claude Sonnet 4.5 | Context: 45% | Quota: 67%, reset 10pm
• I realize I'm using quota quickly and should pace my requests

1. Near quota limit (8pm):

• Statusline shows: Claude Sonnet 4.5 | Context: 12% | Quota: 94%, reset 10pm
• I know I only have 2 hours until reset and 6% quota left
• I decide to save complex tasks for after 10pm when quota resets

1. Without this feature:

• I have no visibility into quota usage
• I might hit the limit unexpectedly during a critical task
• I have to constantly open the UI to check usage
• I waste time context-switching between terminal and browser

Time saved:

• No more switching to UI just to check quota
• Better planning prevents quota exhaustion at critical moments
• Matches the "everything in terminal" philosophy of Claude Code

---
Additional Context:

The UI already has this data (visible in Settings > Usage), so the backend clearly provides it. This feature request is simply to expose existing data to statusline scripts, not to create new tracking infrastructure.

This would be especially valuable for:

• Power users running long sessions
• Teams on usage-based billing who need to monitor consumption
• Users in different timezones who need to know their specific reset time
• Anyone who prefers terminal-based workflows over GUI

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

_No response_

Additional Context

_No response_