Feature Request: Expose /usage data as structured JSON for MCP servers and hooks #26295

Feature Request: Expose /usage data as structured JSON for MCP servers and hooks

Problem

The /usage command in Claude Code CLI only works interactively in the REPL. There is no way to programmatically access usage data (session %, weekly %, extra usage) from:

• MCP servers
• Hooks (SessionStart, Stop, etc.)
• Non-interactive mode (claude --print)
• External scripts

Use Case

I'm building an MCP server plugin that tracks usage limits in real-time and warns the user when approaching session limits. Currently, the only workaround is to:

1. Launch a separate Claude instance with script command to capture terminal output
2. Parse ANSI escape codes from the status bar
3. Extract the usage percentage with regex

This is fragile and only captures the session limit from the yellow status bar - not the full breakdown (session/weekly/extra).

Proposed Solution

Expose /usage data via one or more of these methods:

1. CLI flag: claude --usage or claude usage that outputs JSON:

{
  "session": {"used_percent": 75, "resets_at": "2026-02-17T15:00:00+01:00"},
  "weekly": {"used_percent": 48, "resets_at": "2026-02-18T05:59:00+01:00"},
  "extra": {"spent": 44.33, "limit": 50.00, "resets_at": "2026-03-01T00:00:00+01:00"}
}

2. Hook context: Include usage data in SessionStart and Stop hook payloads

3. MCP resource: Expose as an MCP resource claude://usage that MCP servers can read

4. File-based: Write usage data to ~/.claude/usage.json updated periodically

Environment

• Claude Code v2.1.44
• Claude Pro plan
• Debian Linux

Additional Context

This would enable the community to build usage-aware plugins, auto-save features, and cost management tools. I've already built a working MCP server plugin (usage-tracker) that uses a script command workaround to capture the status bar, but a proper API would be much more reliable.