Add Quota Information Access to Claude Code CLI

Cross-Platform Usage Visibility Gap

This request is even more critical when you consider that Claude Pro usage is shared across all platforms (web, mobile, desktop apps, and Claude Code CLI).

The Problem

Currently, Claude Code has zero visibility into the user's total Claude Pro usage, even though:

• Every message sent via Claude Code counts toward the same Pro quota as web/mobile/desktop
• The web interface at claude.ai shows a usage bar with remaining allowance and reset time
• Third-party tools like ccusage and claude-monitor can only track local JSONL files from Claude Code sessions
• These tools cannot show:
• Total Claude Pro monthly/weekly allowance
• Cross-platform usage (mobile, desktop, web contributions)
• Time until usage limit resets
• Remaining quota percentage

Real-World Impact

CLI-first users who rarely open the web interface have no way to know if they're approaching their limits until they hit them unexpectedly during important work sessions. This is especially problematic because:

• You might use Claude on mobile during the day
• Then switch to Claude Code in the evening
• And have no idea you're at 90% quota already

Additional Solution: Official MCP Server

In addition to the CLI command approach outlined in this issue, consider providing an official MCP server like @anthropic/claude-usage that exposes:

• Current usage percentage across all platforms
• Tokens/messages remaining in current period
• Time until reset
• Optional breakdown by platform

This would enable the entire MCP ecosystem to build quota-aware tools and integrations.

Expected Behavior

Running /usage or a similar command should show the same data visible on claude.ai:

Claude Pro Usage (Week of Jan 6-12, 2026)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Usage:  [████████████░░░░░░░] 62%
Remaining: 38% (15.2M tokens)
Resets in: 3 days, 14 hours

This affects everyone who uses Claude Code as part of a multi-platform workflow, which is likely the majority of Pro users.

+1 for this feature!

One additional idea that could complement the proposed claude quota command: a watch/live mode for real-time monitoring:

# Live mode - continuously updates (for dashboards/widgets)
claude quota --watch
claude quota --watch --interval 30   # refresh every 30 seconds

Watch mode behavior:

• Clears and redraws the output on each refresh (like watch or htop)
• Default refresh interval: 30-60 seconds (to avoid excessive API calls)
• Could be used in a terminal pane, tmux window, or as input for macOS widgets (via JSON output with --json)

This would allow users to keep a small terminal open as a live usage dashboard while working.

+1 on this. The cross-platform visibility gap is the biggest pain point. Local JSONL parsing can approximate CLI usage, but it completely misses consumption from claude.ai, mobile, and desktop apps — so any local tool will always show inaccurate percentages compared to /usage.

An official API endpoint or MCP server exposing the same data as /usage (current %, reset times, per-window breakdown) would be extremely valuable. Even a simple JSON output from claude quota --json would unlock a whole ecosystem of monitoring tools.

Working solution: OAuth usage API endpoint

For anyone building status line integrations, there's already a working endpoint that returns the exact same data as /limits:

GET https://api.anthropic.com/api/oauth/usage

Auth: Bearer token from macOS Keychain:

security find-generic-password -s "Claude Code-credentials" -w
# Returns JSON with claudeAiOauth.accessToken

Response:

{
  "five_hour": {"utilization": 2.0, "resets_at": "2026-02-08T12:00:00+00:00"},
  "seven_day": {"utilization": 35.0, "resets_at": "2026-02-12T03:00:00+00:00"},
  "seven_day_sonnet": {"utilization": 3.0, "resets_at": "2026-02-12T19:00:00+00:00"},
  "seven_day_opus": null
}

utilization values are percentages matching what /limits shows.

I've integrated this into a status line script with 60s caching. Works reliably.

Real-world perspective: building a production macOS app on top of these internal endpoints

I'm the developer of Tokamak for Claude, a macOS menu bar app that monitors Claude Max quota and Claude Code session statistics. It's in the App Store review pipeline right now. I want to share what building on top of internal, undocumented endpoints actually looks like in practice — and why a public API is essential.

What we currently do (and why it's fragile)

Tokamak polls two internal endpoints:

• GET /api/organizations — to discover the user's org UUID and detect plan type (Max/Pro)
• GET /api/organizations/{org_id}/usage — for real-time utilization windows (5h, 7d, 7d-sonnet, 7d-opus, 7d-cowork, etc.)

Authentication requires a sessionKey cookie from claude.ai, obtained via a hidden WKWebView that loads the login page. This is inherently fragile:

1. Cookie-based auth breaks regularly. Cloudflare challenges, cookie rotation, and SameSite policies mean the session can become invalid without warning.
2. No schema contract. The response shape has changed multiple times. We've built a bidirectional schema validation system that captures production responses and compares them against our DTOs to detect drift — because there's no versioned schema to rely on.
3. Undocumented fields appear and disappear. Example: iguana_necktie showed up as a null window one day. seven_day_cowork and seven_day_oauth_apps appeared without any changelog. We handle all windows as optional and degrade gracefully, but this is defensive programming against an API that could break us at any time.
4. Rate limiting is guesswork. We poll every 30s with exponential backoff (up to 5min), but there's no documented rate limit. We've hit 429s and had to guess appropriate retry behavior.

What a public API would unlock

A stable GET /api/v1/usage (or claude quota --json) with:

• Versioned schema — so breaking changes are announced, not discovered
• OAuth or API key auth — instead of session cookies
• Documented rate limits — so tools can poll responsibly
• All quota windows — including the newer ones (cowork, oauth_apps, opus, extra_usage)
• Reset timestamps — already present in the internal API, just needs to be official

This would benefit not just Tokamak but the growing ecosystem: CodexBar, terminal statusline integrations, automation scripts, and anyone who wants to build quota-aware workflows.

The broader ask

Other AI providers already offer this:

• OpenAI: GET /v1/organization/usage with proper API key auth
• GitHub Copilot: Usage metrics in the REST API

Claude is the only major provider where monitoring your own quota requires reverse-engineering internal web endpoints. For a platform that's actively encouraging developers to build with Claude Code, having no official way to check "how much quota do I have left?" is a significant gap.

I'd strongly advocate for Option 1 (CLI command) from the original proposal plus a documented REST endpoint. The CLI command helps individual users; the REST endpoint enables the tool ecosystem.

Happy to help test any beta implementation against Tokamak's existing infrastructure.

Correction to the OAuth endpoint details above — there's a required header that was missing, and the response schema has expanded.

GET https://api.anthropic.com/api/oauth/usage
Authorization: Bearer <access_token>
anthropic-beta: oauth-2025-04-20

Without the anthropic-beta header, the endpoint returns an authentication_error.

Getting the token (macOS):

security find-generic-password -s "Claude Code-credentials" -w \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['claudeAiOauth']['accessToken'])"

Full response (as of Feb 2026):

{
  "five_hour": {
    "utilization": 5.0,
    "resets_at": "2026-02-23T22:00:00.177194+00:00"
  },
  "seven_day": {
    "utilization": 59.0,
    "resets_at": "2026-02-27T01:00:00.177214+00:00"
  },
  "seven_day_oauth_apps": null,
  "seven_day_opus": null,
  "seven_day_sonnet": {
    "utilization": 5.0,
    "resets_at": "2026-02-27T06:00:00.177221+00:00"
  },
  "seven_day_cowork": null,
  "iguana_necktie": null,
  "extra_usage": {
    "is_enabled": true,
    "monthly_limit": 5000,
    "used_credits": 0.0,
    "utilization": null
  }
}

Changes from @trillium's original response format:

• seven_day_oauth_apps, seven_day_cowork, iguana_necktie windows added (all nullable)
• extra_usage object added (tracks overuse billing: enabled status, monthly limit, used credits)

One-liner to test:

curl -s "https://api.anthropic.com/api/oauth/usage" \
  -H "Authorization: Bearer $(security find-generic-password -s 'Claude Code-credentials' -w | python3 -c "import sys,json; print(json.load(sys.stdin)['claudeAiOauth']['accessToken'])")" \
  -H "anthropic-beta: oauth-2025-04-20" | python3 -m json.tool

The gap is blocking real tools from shipping

This issue perfectly captures why proper API exposure matters. We already have:

• Production tools (Tokamak) reverse-engineering internal endpoints to work around this
• Multiple workarounds documented (OAuth endpoint, tmux scraping, local parsing)
• Clear demand from CLI-first users who can't see their quota until they hit the wall

Why this matters for Anthropic:
Making this official would immediately:

1. Replace fragile reverse-engineered solutions with a stable contract
2. Enable the tool ecosystem (statusline widgets, dashboards, quota-aware automation)
3. Bring Claude parity with OpenAI's /v1/organization/usage endpoint

The implementation exists. The OAuth endpoint already returns exactly what /limits shows — just needs to be documented and stable. A simple claude quota --json command or versioned REST API would unblock dozens of tools users are already trying to build.

This isn't a nice-to-have. Users are currently choosing to ignore quota warnings and hit limits unexpectedly because there's no programmatic way to monitor across platforms. That's a UX failure we can fix right now.

Progress on the data access front: since v2.1.80, rate_limits (five_hour/seven_day used_percentage + resets_at) are in the statusline stdin JSON. Not a standalone claude quota --json command yet, but the data is no longer locked behind internal endpoints — statusline scripts can read it without OAuth workarounds.

claude-lens reads these fields for real-time quota display. The Tokamak approach for a full CLI/menu bar solution is complementary.

+1

+1 — Strong use case from building a web UI wrapper around Claude Code CLI.

We're building an internal bug triage tool that spawns Claude Code CLI via child_process.spawn with --output-format stream-json. The web dashboard manages parallel investigation sessions and needs to show operators:

1. Current session usage — so operators know if they can start another investigation or need to wait for reset
2. Weekly usage — to plan investigation workload across the week
3. Reset countdown — to show when capacity becomes available

Currently the only way to see this is in the Claude Code status bar during an interactive session, but our tool runs in --print mode where the status bar isn't available.

Ideal for our case: A claude usage --json command we can poll, or even better, usage info included in the stream-json output events (e.g., a usage_update event type alongside result events). The latter would let us update the dashboard in real-time without additional polling.

This would save us from having to manually track/estimate token budgets as a poor approximation of the actual rate limits.

This is what works reliably for me, on ubuntu:

claude --init-only #Inititialize to refresh auth token for usage request to work
accessToken=$(jq -r '.claudeAiOauth.accessToken' ~/.claude/.credentials.json)
usageResponse=$(curl -s https://api.anthropic.com/api/oauth/usage -H "Authorization: Bearer $accessToken" -H "anthropic-beta: oauth-2025-04-20")
weeklyUsage=$(jq -r '.seven_day.utilization' <<< "$usageResponse" | cut -d. -f1)

In this example, I get the weeklyUsage in bash runtime as a number (eg. 73).
See the full response of https://api.anthropic.com/api/oauth/usage for other metrics, like session usage (five_hour).

I hit this exact wall last month. Claude Code stopped me mid-refactor at what turned out to be 71% weekly, but I had no clue until I opened the desktop app. Burned about 40 minutes guessing whether I could keep going or should switch to Sonnet. The frustrating part is the data already exists, claude.ai/settings/usage renders it from an internal endpoint that returns clean JSON. ccusage and similar local-log tools cannot see it because Anthropic enforces the quota server-side. A claude quota --json command would solve maybe 80% of the daily 'is it worth starting this task' decision.

+1 for usage API for subscription plans

+1

+1

I’d love to see a view like https://claude.ai/settings/usage

ANSI when interactive, markdown when not interactive/--md, simplified JSON

a script I have does this:

ANSI output by default:

## Your usage limits Enterprise - $XX.XX of $500.00 spent — XX% used - Spend limit · Resets Tue, Jun 30, 7:00 PM CDT Claude Design - A separate allowance to try Claude Design. After it's used up, Claude Design will draw from your normal usage. - Included allowance · Doesn't reset — 0% used _Last updated: 9:21 AM CDT_ --- ℹ️ This info may be available in the CLI eventually — please 👍 feel free to upvote <https://github.com/anthropics/claude-code/issues/13585#issuecomment-4613598049> to help make it happen.

⚛︎ # claude-spend --md # non-interactive does this too (claude-spend | cat)
## Your usage limits

**Enterprise**
- $XXX.XX of $500.00 spent — XX% used
- Spend limit · Resets Tue, Jun 30, 7:00 PM CDT

**Claude Design**
- A separate allowance to try Claude Design. After it's used up, Claude Design will draw from your normal usage.
- Included allowance · Doesn't reset — 0% used

_Last updated: 8:55 AM CDT_

---

ℹ️  This info may be available in the CLI eventually — please 👍 [feel free to upvote](https://github.com/anthropics/claude-code/issues/13585#issuecomment-4613598049) to help make it happen.
⚛︎ # claude-spend --json
{
  "subscription": "Enterprise",
  "spend_limit": {
    "used": XXX.XX,
    "limit": 500,
    "currency": "USD",
    "utilization_pct": XX,
    "resets_at": "2026-07-01T00:00:00Z",
    "resets_at_display": "Tue, Jun 30, 7:00 PM CDT"
  },
  "claude_design": {
    "utilization_pct": 0,
    "resets_at": null,
    "resets_display": "Doesn't reset"
  },
  "last_updated": "8:55 AM CDT"
}

• portable
• barfs if auth token not set up
• has --help/-h and fails on unknown flags

+1 — a concrete use case for subscription (Pro/Max, OAuth) users running headless.

We run Claude Code headless in a container and want to surface remaining quota + reset time on an ops dashboard. Today there's no programmatic tap for it:

• /usage shows it but is interactive-only — no JSON/export.
• claude -p --output-format json returns per-turn tokens + cost, but no remaining-quota / reset fields.
• OpenTelemetry (CLAUDE_CODE_ENABLE_TELEMETRY=1) exposes consumption metrics only — no limit/quota-utilization gauge.
• anthropic-ratelimit-* headers are API-key only, not surfaced for subscription CLI.

A JSON-exportable usage view (e.g. claude usage --output-format json, or the statusLine/limit fields proposed in #12520) returning rolling-window % used + reset timestamp would close the gap. Consumption is observable; remaining capacity is the missing half. Thanks!

+1 to what @lorenzowood just laid out, that's the exact gap left now that @Astro-Han's statusline fix (v2.1.80, rate_limits) landed. One more spot worth adding to that list: hooks don't get rate_limits either, even though hookSpecificOutput.additionalContext already lets a hook feed text straight into the model's context. Right now the only way around that is the same /api/oauth/usage endpoint several people above have flagged as fragile (schema drift, surprise 429s). Putting rate_limits in hook input and in --output-format json would cover the statusline, hooks, and headless cases in one change instead of three separate asks.

The rate_limits statusline addition helps interactive Claude Code sessions. The remaining gap is a stable JSON surface for headless use: hooks, CI wrappers, dashboards, and shell/statusline renderers outside Claude Code's statusline stdin.

I'd like claude quota --json or --output-format json to define freshness and failure behavior, not only return usage numbers. Useful fields/semantics would include:

• fetched_at
• stale: true|false or source: "live"|"cache"
• reset timestamps as ISO strings
• nullable windows when a plan/account does not expose a limit
• documented cache TTL and minimum recommended poll interval
• defined behavior for expired auth, 401s, network failures, and schema changes
• quiet failures for render-only modes, so terminal UI is not interrupted when quota is unavailable

The lesson from ax quota was that percentages were straightforward; the hard part was deciding whether the data was live, cached, or stale fallback, and making statusline/menubar integrations fail quietly.

Concrete ask: expose quota through a stable JSON contract that includes both quota values and freshness metadata, so downstream tools can decide whether to show, hide, or label stale data.

---

_Generated with ax._

Now I use CLI to get usage every 15mins, have both web and PICO version.
!image

+1 on this. One specific angle worth including in the design: it'd be great if usage/quota data could also be surfaced within an active session (e.g. via a hook, or fields injected into additionalContext/statusLine input), not just as a standalone claude quota CLI print. That would let the assistant itself read current quota state mid-conversation and proactively flag "you're at 80% of your session limit" rather than requiring the user to run /usage and relay the number manually.

For anyone looking for a stopgap while waiting for an official claude quota command, I built a tiny local-only dashboard that queries the OAuth usage endpoint and shows Claude Code Max session/weekly limits (plus Kimi and Z.ai if you add those tokens). Tokens stay in your browser and are only sent to the provider APIs.

https://ryan-knowone.github.io/quota-dashboard/

It obviously doesn't replace a native CLI command, but it's useful for the "am I about to hit my weekly cap?" check that currently requires opening the desktop app.