[FEATURE] Add CLI flag to output usage/quota information non-interactively

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 /usage slash command shows subscription quota information (session limits, weekly limits, reset times) but only works within an interactive Claude Code session. There's no way to retrieve this information programmatically from the command line.

I want to monitor my usage limits without starting an interactive session - either as a quick check or as a live dashboard/widget that updates in real-time as I work.

Proposed Solution

Add a --usage flag (or usage subcommand) that outputs quota information and exits:

# Simple text output
claude --usage

# JSON output for scripting
claude --usage --output-format json

# Live/watch mode - continuously updates (for dashboards/widgets)
claude --usage --watch
claude --usage --watch --interval 30   # refresh every 30 seconds

Example output (text)

Current session:       37% used (resets 4:59pm)
Current week (all):    54% used (resets Jan 26 at 1:59pm)
Current week (Sonnet):  0% used

Example output (JSON)

{
  "session": {
    "used_percent": 37,
    "resets_at": "2026-01-23T16:59:00Z"
  },
  "week_all_models": {
    "used_percent": 54,
    "resets_at": "2026-01-26T13:59:00Z"
  },
  "week_sonnet": {
    "used_percent": 0,
    "resets_at": "2026-01-26T13:59:00Z"
  }
}

Watch mode behavior

• Clears and redraws the output on each refresh (like watch or htop)
• Default refresh interval: 30-60 seconds (to avoid excessive API calls)
• Could be used in a terminal pane, tmux window, or as input for macOS widgets (via JSON output)

Alternative Solutions

• Parsing ~/.claude/stats-cache.json - only contains local usage stats, not subscription limits
• Using expect to automate the interactive session - fragile and slow
• Third-party tools - require additional dependencies

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

1. I'm working with Claude Code throughout the day on multiple projects
2. I want to keep track of my session/weekly limits without interrupting my workflow
3. With this feature, I could run claude --usage --watch in a small terminal pane or feed claude --usage --output-format json to a macOS widget
4. This would let me see my usage grow in real-time and know when I'm approaching limits before getting rate-limited