ccusage

Claude Code usage monitor. Fetches your real rate limit data from Anthropic's API and displays it in the Claude Code statusline.

Example output

ccusage command:

Plan: max_5x
  Session              39%  resets 1h26m
  Week (all)           15%  resets 143h26m
  Week (Sonnet)        39%  resets 65h26m
  Extra usage          $0.00 / $1000.00

Claude Code statusline (self-caching — refreshes from API when stale, no daemon needed):

~/projects/myapp [Opus 4.6] sess:39% 7d:15% son:39% | $1.37 | max_5x | reset:1h26m

Install

uv tool install ccusage

Then run:

# Check usage once
ccusage

# Run the daemon (keeps usage-limits.json updated)
ccusage daemon

Configure the statusline in ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "ccusage statusline"
  }
}

If Claude Code uses CLAUDE_CONFIG_DIR, ccusage reads credentials and writes usage-limits.json in that directory instead.

Commands

How Claude Code rate limiting works

Discovered by inspecting Claude Code's bundled cli.js (v2.1.32).

Data sources

Claude Code gets rate limit data from two places:

1. /api/oauth/usage endpoint — Called by the /status slash command. Returns utilization percentages and reset times for each rate limit bucket. Requires the anthropic-beta: oauth-2025-04-20 header.

2. Response headers on every API call — Every message response includes headers like:

   • anthropic-ratelimit-unified-{claim}-utilization (0-100 float)
   • anthropic-ratelimit-unified-{claim}-reset (unix timestamp)
   • anthropic-ratelimit-unified-status (allowed / allowed_warning / rejected)
   • anthropic-ratelimit-unified-fallback (available when fallback models are available)
   • anthropic-ratelimit-unified-overage-status / overage-reset
   • anthropic-ratelimit-unified-representative-claim

Rate limit types

The flat seven_day_* keys above are all null now — the live quota data lives in a structured limits array, which ccusage reads. Each entry is self-describing: kind (session / weekly_all / weekly_scoped), percent, resets_at, and for scoped limits a scope.model.display_name. Because the structured response does not include a session duration, ccusage labels that limit Session and caches it under session rather than assuming it is always five hours. Existing 5h cache files remain readable. Model-scoped weekly windows (Opus, Sonnet, and a newly added Fable) are keyed by their model name, so any new one is auto-detected and displayed with no code change (e.g. scope.model.display_name: "Fable" → "Week (Fable)", statusline fab:).

API response format

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

{
    "five_hour": {
        "utilization": 35.0,
        "resets_at": "2026-02-06T22:00:00+00:00"
    },
    "seven_day": {
        "utilization": 14.0,
        "resets_at": "2026-02-12T20:00:00+00:00"
    },
    "seven_day_sonnet": {
        "utilization": 39.0,
        "resets_at": "2026-02-09T14:00:00+00:00"
    },
    "seven_day_opus": null,
    "seven_day_oauth_apps": null,
    "seven_day_cowork": null,
    "iguana_necktie": null,
    "extra_usage": {
        "is_enabled": true,
        "monthly_limit": 100000,
        "used_credits": 0.0,
        "utilization": null
    }
}

Authentication

The OAuth token normally lives at ~/.claude/.credentials.json, or under CLAUDE_CONFIG_DIR when that environment variable is set:

{
    "claudeAiOauth": {
        "accessToken": "sk-ant-oat01-...",
        "refreshToken": "sk-ant-ort01-...",
        "expiresAt": 1770412938485,
        "subscriptionType": "team",
        "rateLimitTier": "default_claude_max_5x"
    }
}

The access token expires roughly hourly. When it's expired (or rejected with a 401/403), ccusage refreshes it itself using the refreshToken and writes the rotated credentials back to .credentials.json — the same flow Claude Code uses, so the two stay in sync and no active Claude Code session is needed.

Warning thresholds (from cli.js)

Claude Code shows inline warnings based on these thresholds:

five_hour:  90% utilization when 72% of window has passed
seven_day:  75% at 60%, 50% at 35%, 25% at 15%

Other endpoints found in cli.js

• /api/oauth/profile — User profile
• /api/oauth/account/settings — Account settings
• /api/claude_code/policy_limits — Org policy limits (needs organizationUuid)
• /api/organization/claude_code_first_token_date — Org onboarding date

Local files Claude Code uses