[FEATURE] Expose subscription usage (Pro/Max) via a documented API or CLI command

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

## Summary

Pro/Max subscribers can see their session and weekly usage at
https://claude.ai/settings/usage, but there's no documented way to
read those same numbers programmatically. Please expose them via a
supported endpoint or a claude subcommand.

## Problem

Heavy Claude Code users — especially those running it across multiple
machines or shells — want to keep an eye on their quota without
context-switching to the browser. Today the only options are:

1. ccusage and similar JSONL-based tools — these tally tokens

from ~/.claude/projects/, which works for a single machine but
can't aggregate usage across installs and doesn't know about the
actual server-side quota counters (5-hour window, weekly limit).

1. **The undocumented GET /api/organizations/{org_id}/usage

endpoint** that claude.ai/settings/usage itself calls. Several
community tools (sshnox/Claude-Usage-Tracker,
hamed-elfayome/Claude-Usage-Tracker, lugia19/Claude-Usage-Extension,
phuryn/claude-usage) rely on this with a scraped session cookie. It
works, but it's brittle, undocumented, and arguably outside the
spirit of the ToS.

1. The Admin API (Usage and Cost API, Claude Code Analytics API) —

documented and supported, but requires an Organization Admin API
key. Not available to individual Pro/Max subscribers.

So there's a real gap between "official + supported" and "actually
usable for an individual subscriber."

Proposed Solution

Either (or both) of:

• claude usage --json — a Claude Code subcommand that returns

the current 5-hour-window and weekly usage as structured JSON,
authenticated by the same credentials the CLI already has.

• A documented endpoint with the same data, callable with a

user-scoped token (not Admin-only).

The shape returned by /api/organizations/{org_id}/usage is already
roughly what's needed; this is mostly about making it supported.

## Use cases this unlocks

• Desktop panel/menu-bar widgets (GNOME Shell extension, macOS menu

bar, Windows tray) showing live quota.

• Shell prompt indicators (PS1 / starship segment).
• CI/pre-commit guards that warn before kicking off long agent runs

near the weekly limit.

• Team dashboards aggregating usage across multiple developers'

installs.

Today people are building all of these against the unofficial
endpoint; a supported surface would let the ecosystem stop depending
on something that can break without warning.

## Multi-install angle

The reason a local-only solution (ccusage) doesn't close this gap:
many of us run Claude Code on several machines (workstation, laptop,
remote dev box). The JSONL on any one machine only shows that
machine's portion. The server-side quota is the only source of truth
for total usage, which is exactly why the settings page exists.

## Related

• https://github.com/sshnox/Claude-Usage-Tracker
• https://github.com/hamed-elfayome/Claude-Usage-Tracker
• https://github.com/phuryn/claude-usage
• https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor

Alternative Solutions

_No response_

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_