[FEATURE] Expose /usage data in statusLine JSON input #8464

Preflight Checklist

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

Problem Statement

Summary
Add usage metrics from the /usage command to the JSON input provided to custom statusLine scripts, enabling users to display real-time usage stats in their status line.

Motivation
Currently, the /usage command provides valuable information about:

• Current session usage percentage
• Session reset time
• Weekly usage (all models)
• Weekly usage (Opus)

However, this data is not accessible to custom statusLine scripts. The JSON input to statusLine only includes:

• cost.total_cost_usd (cumulative session cost)
• exceeds_200k_tokens (boolean flag)

Users who want to display usage stats in their status line must either:

1. Estimate incorrectly from cost data (which is cumulative, not window-based)
2. Run /usage manually to check their limits

Proposed Solution

Add a usage object to the JSON input passed to statusLine scripts:

{
  "session_id": "...",
  "transcript_path": "...",
  "cwd": "...",
  "model": { ... },
  "workspace": { ... },
  "version": "...",
  "cost": { ... },
  "exceeds_200k_tokens": false,
  "usage": {
    "current_session": {
      "percentage": 15,
      "reset_time": "2025-09-30T19:00:00+05:00",
      "timezone": "Asia/Almaty"
    },
    "current_week_all_models": {
      "percentage": 1,
      "reset_time": "2025-10-07T14:00:00+05:00",
      "timezone": "Asia/Almaty"
    },
    "current_week_opus": {
      "percentage": 0,
      "reset_time": "2025-10-07T14:00:00+05:00",
      "timezone": "Asia/Almaty"
    }
  }
}

Benefits

1. Accurate usage display - Users can show real-time usage percentages in their status line
2. Better resource awareness - At-a-glance visibility of approaching limits
3. Consistent with existing patterns - Follows the same structure as existing cost object
4. No breaking changes - Additive change, backward compatible

Example Use Case
With this data available, a statusLine script could display:
ctx: 29% 🟢 | t: 15% 🟢 | s: 4h33m left 🔴 | myproject main
Where:
ctx = context window usage (from transcript size)
t = token usage from actual /usage data
s = time until session reset

Would you consider adding this feature? It would greatly enhance the statusline customization capabilities introduced in recent versions.

Alternative Solutions

Current Workaround
Currently using estimated calculations based on cost.total_cost_usd, but this is inaccurate because:

• Cost is cumulative across the entire conversation
• Window-based limits reset at specific times
• No way to know which time window the user is in

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

No response

Additional Context

• Custom statusLine feature introduced in v1.0.71
• /usage command introduced in v2.0.0
• Existing cost object provides session-level data