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.

There is the undocumented api endpoint that provides all this info, without the need for a AnthropicsAPIkey, but unfortunately its probably against TOS.

Its the same exact endpoint that the App desktop/mobile app uses to show you what your at.
https://claude.ai/api/organizations/{orgID}/usage

You still have to be logged in to use it though.

The ask here is @amphro's, unchanged — rate_limits in hook input, and available headless. I want to add the part I have not seen stated: a session cannot learn which account governs it, so a quota reading can be confidently wrong and look completely normal.

That is the failure I care about, and it is not budgeting. With several concurrent sessions on one account-wide pool, the thing that costs real work is a session hitting a cutoff mid-task with uncommitted changes. The whole point of reading quota is to commit and hand off before that happens — so a number that is wrong is worse than no number at all, because it is the number a session uses to decide it is safe to keep going.

The payload names no account. rate_limits describes a per-account pool without identifying which account it belongs to, and nothing else in a session's inputs does either. So a monitor has to hardcode which credentials to read. On a box with more than one Claude account signed in, it will happily display another account's headroom, labelled as this session's, with no indication anything is off. Mine did exactly that — the warning banner every session sees names an account that does not necessarily govern that session.

And the one surface that carries rate_limits has no host on two of the three ways I run Claude Code. It arrives on a statusLine command's stdin and nowhere else, so quota state cannot be subscribed to — it has to be collected by a statusLine and published somewhere shared, which forces a one-publisher/N-readers design nobody would choose. Then:

• The statusLine is part of the TUI render tree, so it never executes under claude -p or the SDK. A headless coordinator can read what an interactive session publishes and can never publish it itself — backwards from where the need is.
• I work in the desktop app, which renders no status line. My collector is correctly wired and has never executed once: the first thing its command does is append to a heartbeat log, and that log does not exist, nor do either of its publish targets. (Strictly that shows it has not run since I added the heartbeat line — but there is no status line for it to run in, which is the simpler reading.)

So the documented workaround everyone in this thread is describing — collect from a statusLine, publish to a file — has nowhere to run for a desktop or headless user. That is why I would rather have it in hook input than have the statusLine path improved.

One ask, then: rate_limits in the SessionStart / UserPromptSubmit hook payload, or a headless-capable JSON usage output — plus whatever identifies the account the numbers belong to. The second half is small and it is what makes the first half safe to act on.

Separately and minor: the payload carries five_hour and seven_day only — no per-model bucket. That was raised in #37227, which went stale, was auto-closed after inactivity and is now locked, so it reads as unresolved rather than decided. It matters here only because a green reading on the two visible windows says nothing about a third that could stop you.

Setup: Windows 11, 2.1.219, solo dev, several concurrent sessions on one account. n=1.

+1 to this issue/feature. Would be extremely helpful for automation, dashboards etc.

Adding a data point that I think narrows this request considerably: the CLI
already computes and returns this, for free. It just returns it as prose.

$ claude -p "/usage" --output-format json

The envelope reports total_cost_usd: 0, input_tokens: 0, output_tokens: 0,
num_turns: 0, duration_api_ms: 0. It is answered client-side from state the
client already holds, costs no quota, makes no API call, and returns in about
2.5 seconds. The numbers are account-wide, matching what claude.ai/settings/usage
reports, not a local approximation.

The problem is that it lands in .result as human text:

Current session: 8% used · resets Aug 25, 2:29pm (America/Los_Angeles)
Current week (all models): 85% used · resets Aug 26, 7:59pm (America/Los_Angeles)
Current week (Fable): 0% used

So consumers regex it, and prose is not a contract. A concrete failure I hit
building on this: the minutes are omitted on the hour, so the same reset renders
as either 7:59pm or 8pm depending on sub-second rounding of a 7:59:59.x
instant, and it genuinely alternates between calls. My parser required H:MM,
matched roughly two calls in three, and silently produced a null reset on the
rest. Nothing errored; a scheduler downstream just started pacing against a
missing value.

Without a supported path, what I had before this was worse: Playwright driving a
real Chrome under Xvfb against claude.ai/api/organizations/<org>/usage, because
that endpoint sits behind Cloudflare and rejects non-browser requests. It needs a
logged-in browser profile on the machine, breaks whenever the page changes, and
is not something I would ask anyone else to run.

My use case is pacing unattended work: deciding whether to start a long job now
or wait for the 5-hour window to reset, and staying inside the weekly allowance.
That needs the reset timestamps as much as the percentages.

One gap worth naming, because it is the only reason I cannot delete the scraper
outright: /usage does not report extra-usage credits, and /usage-credits
returns a link rather than the numbers.

$ claude -p "/usage-credits" --output-format json | jq -r .result
Visit https://claude.ai/settings/usage?from=cc_cli_limit_message to manage usage credits.

I am not asking for that here, and I barely use credits. I mention it only
because it is the remaining reason a browser-scraping path exists at all in my
setup.

Two minimal shapes, either of which would be enough:

1. Emit structured fields alongside .result when --output-format json is

passed, since the values already exist at that point.

1. Or include them in the statusline payload, which already carries

cost.total_cost_usd and context_window and is polled by exactly the
tooling that wants this.

Happy to test either.