Feature Request: Expose subscription usage data via local file or API

Summary

Provide a way for users and tools to programmatically access Claude Code Pro/Max subscription usage data (session and weekly quota percentages, reset times).

Problem

Currently, the only way to check subscription usage is via the /usage command, which:

• Displays data in the terminal but doesn't expose it programmatically
• Fetches from Anthropic's servers but doesn't cache locally
• Cannot be invoked by external tools or scripts

This makes it impossible to build companion tools that help users:

• Monitor usage in real-time
• Get alerts before hitting limits
• Track usage patterns over time
• Plan sessions efficiently

Proposed Solution

One or more of the following:

Option A: Local cache file

Write usage data to a local file (e.g., ~/.claude/usage-cache.json) after each /usage call or periodically:

{
  "session": {
    "percentUsed": 59,
    "resetIn": "2h 47m",
    "resetAt": "2026-01-30T15:30:00Z"
  },
  "weekly": {
    "percentUsed": 29,
    "resetDay": "Wednesday",
    "resetAt": "2026-02-05T11:29:00Z"
  },
  "updatedAt": "2026-01-30T12:43:00Z"
}

Option B: Machine-readable /usage output

Add a flag like /usage --json that outputs structured data instead of formatted text.

Option C: Include in stats-cache.json

Extend the existing ~/.claude/stats-cache.json to include current quota status.

Use Cases

1. CLI companion tools - Build dashboards showing real-time usage
2. Alerts - Get notified before hitting session/weekly limits
3. Planning - Tools that help distribute usage across the week
4. Automation - Scripts that pause work when approaching limits

Current Workaround

Users must manually read /usage output and input numbers into external tools - this is error-prone and tedious.

Additional Context

The API already returns rate limit headers (anthropic-ratelimit-*) for per-minute limits. Extending this pattern to subscription quotas would be consistent and helpful.

Related: The existing stats-cache.json already tracks token usage but lacks quota context.