[FEATURE] Team seat usage is available in `/usage` but inaccessible to local integrations

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

Description

Claude Code can display personal subscription usage for a Claude Team member seat through /usage, including the member's own 5-hour and weekly limits.

However, there does not appear to be a supported machine-readable way for local companion applications or integrations to access the same Team-seat usage data.

This is especially noticeable because Claude Code already has the data and can display it interactively, while the authenticated Team member's Claude Code OAuth credentials cannot retrieve the equivalent usage data programmatically.

Current behavior

Environment:

• Claude Code: 2.1.153
• macOS, Apple Silicon
• Claude Team subscription
• Organization role: regular member
• Claude Code OAuth login works normally
• Inference works normally

The Team member has individual usage limits visible in Claude, including:

• 5-hour usage
• 7-day usage
• model-scoped weekly usage, e.g. Fable
• usage credits / spend limit

Claude Web's member Usage page returns data such as:

{
  "limits": [
    {
      "kind": "session",
      "group": "session",
      "percent": 30,
      "resets_at": "..."
    },
    {
      "kind": "weekly_all",
      "group": "weekly",
      "percent": 64,
      "resets_at": "..."
    },
    {
      "kind": "weekly_scoped",
      "group": "weekly",
      "percent": 76,
      "scope": {
        "model": {
          "display_name": "Fable"
        }
      }
    }
  ]
}

The organization UUID is also already available locally through Claude Code state (oauthAccount.organizationUuid).

However, the Claude Code OAuth credential used successfully for inference receives HTTP 403 Forbidden when attempting to retrieve subscription usage through the OAuth usage path.

As a result, local tools cannot obtain the same Team member usage information that Claude Code itself can already display.

Expected behavior

There should be a supported, read-only, machine-readable way to obtain the authenticated user's own subscription usage, including for Team member seats.

For example, any of the following would work:

claude usage --json

or:

• include subscription utilization in --output-format stream-json
• expose it through status-line/hook JSON
• provide a supported local SDK/API method
• allow Team member Claude Code OAuth credentials read-only access to their own usage

Ideally the structured data would include:

• 5-hour utilization and reset time
• weekly utilization and reset time
• scoped weekly limits such as Fable
• extra usage / usage-credit spend and limits

Why this matters

This is not a request for:

• organization-wide analytics
• billing administration
• Admin API access
• another member's usage

It is only a request for machine-readable access to the currently authenticated Team member's own usage, which Claude Code already has enough access to display interactively.

This would allow local companion applications, status tools, IDE integrations, and other Claude Code tooling to display accurate subscription utilization without relying on undocumented endpoints or browser-session cookies.

Additional context

There are already related feature requests for exposing subscription usage programmatically, but this issue is specifically about Team-seat parity: a Team member can use Claude Code normally and view personal usage interactively, yet the same local authenticated environment cannot expose that usage to integrations.

If direct OAuth access is intentionally unavailable for Team seats, exposing the data through a supported local Claude Code interface such as claude usage --json would also solve the problem.

Proposed Solution

Expose the authenticated user's plan usage through a supported machine-readable interface that external local clients can consume, not only through the interactive /usage UI.

The main use case is companion applications such as Paseo, IDE integrations, status dashboards, launchers, and other local Claude Code clients that already work with the user's Claude Code installation and authentication.

Ideally Claude Code would expose a stable interface such as:

claude usage --json

For example:

{
  "rate_limits": {
    "five_hour": {
      "used_percentage": 30,
      "resets_at": "..."
    },
    "seven_day": {
      "used_percentage": 64,
      "resets_at": "..."
    },
    "scoped": [
      {
        "name": "Fable",
        "used_percentage": 76,
        "resets_at": "..."
      }
    ]
  },
  "extra_usage": {
    "enabled": true,
    "used": 50.89,
    "limit": 50.00,
    "currency": "USD"
  }
}

A local API/IPC interface, SDK method, or another stable structured interface would also work. The specific transport is less important than providing a supported contract for local clients.

The important requirements are:

• It should work using the user's existing Claude Code authentication.
• It should expose only the authenticated user's own plan usage.
• It should work for subscription-backed accounts including Team member seats.
• It should include 5-hour, weekly, model-scoped limits such as Fable, and usage-credit information when applicable.
• It should not require browser session cookies, browser-cookie extraction, or organization-admin credentials.
• External clients should not need to depend on undocumented Anthropic or Claude Web endpoints.

This would allow applications such as Paseo to show the same usage information that Claude Code already shows in /usage, while keeping authentication and usage retrieval owned by Claude Code itself.

Alternative Solutions

I considered several alternatives, but none provide a complete or supported solution for external clients such as Paseo.

1. Read the interactive /usage output

Claude Code already shows the relevant information through /usage.

This works for a human user, but it is not a stable machine-readable interface that a companion application can consume. Parsing terminal UI output would be fragile and implementation-dependent.

2. Use the existing statusLine rate-limit data

Claude Code exposes some rate-limit information to status-line scripts, so a local client could potentially build around that.

However, this is currently incomplete for my use case. The basic 5-hour and 7-day windows may be available, but model-scoped weekly limits such as Fable and other usage details are not consistently exposed.

It also requires running a Claude Code session and treating status-line output as an indirect data transport rather than providing a dedicated usage interface.

3. Call the Claude Web usage endpoint

Claude Web itself can retrieve the Team member's full usage information, including 5-hour, weekly, scoped limits, and usage credits.

However, that endpoint relies on the user's Claude Web browser session. A third-party local client would therefore need to obtain or store browser-session credentials.

I do not consider browser-cookie extraction or session-cookie sharing an acceptable workaround for a local integration.

4. Reuse Claude Code OAuth credentials directly

I tested whether the existing Claude Code OAuth authentication could provide the same Team-member usage data.

For my Team seat, the OAuth usage path returns 403 Forbidden, despite Claude Code itself working normally for inference.

Therefore an external client cannot currently rely on the user's existing Claude Code OAuth credentials to obtain this data.

5. Manually copy usage into the companion application

The remaining workaround is simply checking /usage or Claude's Usage page and manually transferring the values into another application.

This defeats the purpose of a usage dashboard and quickly becomes stale as usage and reset times change.

For these reasons, a supported machine-readable interface owned by Claude Code itself seems preferable. It would allow clients such as Paseo to consume the authenticated user's usage without scraping terminal output, depending on undocumented endpoints, or handling browser credentials.

Priority

Critical - Blocking my work

Feature Category

Developer tools/SDK

Use Case Example

I use a local companion client such as Paseo to manage and monitor multiple coding agents, including Claude Code.

A typical workflow looks like this:

1. I sign in to Claude Code normally using my Claude subscription. Claude Code already knows my account and can show my current plan usage through /usage.
2. I launch Claude Code sessions through Paseo instead of keeping a separate terminal open for every agent.
3. Paseo shows the status of each provider and should ideally also show the remaining Claude plan usage alongside the active session.
4. Before starting a large task, I want to see whether I am at, for example, 30% of my 5-hour window, 64% of my weekly allowance, or close to a scoped model limit such as Fable.
5. Paseo could read this information from a supported Claude Code interface and display it without needing access to browser cookies, private web endpoints, or Claude authentication credentials.
6. When the usage approaches a limit, Paseo could warn me before I start another long-running task or help me decide which available provider to use.

Today, Claude Code can display this information interactively, but companion applications cannot reliably consume the same complete usage state through a supported interface. Similar requests from the Claude Code community specifically mention dashboards, alerts, companion tools, MCP servers, and external scripts as use cases for machine-readable subscription usage.

The ideal experience is that Claude Code remains responsible for authentication and fetching usage, while a local client such as Paseo receives only a read-only structured usage snapshot.

Additional Context

_No response_