Expose /usage plan usage data programmatically (hooks, CLI, or local file)

Feature Request

Problem

The /usage command displays valuable plan usage data (session %, weekly %, reset times), but this data is only available as an interactive UI widget. There is no way to access it programmatically — it's not passed to hooks, not available via CLI flags, and not written to any local file.

Current behavior

• /usage renders an interactive settings panel with usage bars
• Data shown includes:
• Current session usage % and reset time
• Current week (all models) usage % and reset time
• Current week (Sonnet only) usage % and reset time
• This data is fetched from Anthropic's servers and displayed only in the TUI
• Hooks (SessionEnd, Stop, etc.) receive token counts via transcripts but NOT plan-level usage percentages

Desired behavior

Expose the /usage data through one or more of these channels:

1. Hook input fields — Add usage object to SessionEnd (and ideally Stop) hook input JSON:

``json
{
"session_id": "abc123",
"transcript_path": "...",
"usage": {
"current_session": { "used_percentage": 16, "resets_at": "2026-02-09T14:00:00-05:00" },
"current_week_all": { "used_percentage": 27, "resets_at": "2026-02-11T15:00:00-05:00" },
"current_week_sonnet": { "used_percentage": 1, "resets_at": "2026-02-13T14:00:00-05:00" }
}
}
``

1. CLI output — A flag like claude usage --json or claude --print-usage that outputs the data as JSON to stdout.

1. Local file — Write usage snapshots to a file (e.g., ~/.claude/usage.json) that external tools can read.

Use case

I'm building a SessionEnd hook that logs session metrics to Obsidian daily notes for personal usage tracking. I want to see whether I'm consistently hitting my plan limits or if I could downsize to a cheaper plan.

Currently I can track tokens, messages, and tool calls from transcript files, but the actual plan usage percentage (which accounts for model weighting, caching discounts, etc.) is the metric that matters for billing decisions — and it's the one thing I can't capture.

I imagine others in the community would find this useful for:

• Personal usage dashboards
• Team usage monitoring and reporting
• Automated alerts when approaching plan limits
• Data-driven plan selection decisions

Environment

• Claude Code v2.1.37
• Claude Team (Max) plan
• macOS