claude-code - 💡(How to fix) Fix [FEATURE] Expose subscription usage (Pro/Max) via a documented API or CLI command [3 comments, 3 participants]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• 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).

2. 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.

3. 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