Expose Usage/Rate Limit Data to Status Line Scripts

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

Currently, the status line script receives session cost and context window data, but does not have access to the subscription usage/rate limit information that is displayed by the /usage command. This creates a disconnect where users cannot display their current session and weekly usage percentages in their custom status lines.

Current Behavior

The status line script receives this JSON structure:

{
  "session_id": "...",
  "model": {"id": "...", "display_name": "Opus 4.5"},
  "workspace": {...},
  "cost": {
    "total_cost_usd": 0.253105,
    "total_duration_ms": 594207,
    "total_api_duration_ms": 72004,
    "total_lines_added": 0,
    "total_lines_removed": 0
  },
  "context_window": {...}
}

The /usage command shows:

• Current session: X% used (resets 4pm)
• Current week (all models): Y% used (resets Jan XX, Xpm)
• But this data is not available to status line scripts.

Proposed Solution

Add a usage object to the status line JSON input with the same data available from /usage:

{
  "session_id": "...",
  "model": {...},
  "workspace": {...},
  "cost": {...},
  "context_window": {...},
  "usage": {
    "session": {
      "used": 12500,
      "limit": 625000,
      "percentage": 2,
      "resets_at": "2026-01-17T16:00:00Z",
      "timezone": "Europe/Madrid"
    },
    "week": {
      "used": 343750,
      "limit": 625000,
      "percentage": 55,
      "resets_at": "2026-01-19T18:00:00Z",
      "timezone": "Europe/Madrid"
    }
  }
}

Alternative Solutions

Currently, there is no workaround. The usage data is only accessible via the /usage command and is not exposed to any programmatic interface within status line scripts.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Users want to monitor their usage at a glance in the status line without having to run /usage repeatedly. This is especially useful for:

• Avoiding rate limit surprises
• Planning heavy usage sessions
• Tracking consumption patterns throughout the week

Example Status Line Display

With this data available, users could display:

Opus 4.5 | [=====       ] 25% | 50K/200K | S:2% | W:55% | master | my_project

Where S:2% shows session usage and W:55% shows weekly usage.

Additional Context

• Version: Claude Code 2.1.11
• OS: Ubuntu (bash terminal)
• Custom status line script location: ~/.claude/statusline-command.sh