📊 claude-usage

Your Claude subscription limits — right from your terminal.

Claude Code shows your subscription limits only in the interactive /usage screen. claude-usage gives you the same two numbers from the shell — for scripts, hooks, and AI agents deciding when to back off. It uses the Claude Code login already on your machine. No API key to manage, nothing to configure.

Install claude-usage-limits from PyPI; the command is claude-usage.

$ claude-usage
5-hour: 25% used, resets 16:10 (in 1h39m)
7-day:  59% used, resets Sun 03:00 (in 12h29m)

✨ Features

• Two windows, one command — 5-hour and 7-day percent used and local reset times.
• 🚦 Thresholds for scripts — --warn [N] and --warn-7d [N] exit 1 at or above N%.
• 📊 Extra detail — --all shows per-model limits, the active window, and the weekly surface split.
• 📟 Status line — a compact model and usage line that also feeds the documented fallback source.
• 🧾 Plain, JSON, or short — readable in a terminal and easy to use from scripts.
• 🌍 Cross-platform — macOS, Linux, and Windows; Python 3.9+.
• 🔋 Zero dependencies — pure Python standard library.
• 🔒 Local & private — reads your existing login; no telemetry or third-party calls.

🚀 Quickstart

pip install claude-usage-limits
claude-usage

Sign in with claude on this machine first. Any running Claude Code session keeps its access token fresh.

🧑‍💻 Usage

Flags combine: claude-usage --format short --warn 70 --warn-7d 90. --json and --format set the same option; the last one wins. --all adds detail only in plain format, keeping JSON machine-readable and short output on one line.

5-hour: 30% used, resets 16:10 (in 1h21m)
7-day:  60% used, resets Sun 03:00 (in 12h11m)
kind             percent  severity   active  model        reset
------------------------------------------------------------------------------
session              30%  normal                          resets 16:10 (in 1h21m)
weekly_all           60%  normal     active               resets Sun 03:00 (in 12h11m)
weekly_scoped         9%  normal             Fable        resets Sun 03:00 (in 12h11m)
Claude Code 96%, Cowork 4%, Chats 0%, Other 0%

🤖 Using it from scripts and agents

claude-usage --warn 70 || echo "back off"
claude-usage --warn 70 --warn-7d 90 --format short
claude-usage --json

The usual output is always printed. Exit codes: 0 for success, 1 when either threshold trips or no source answers, 2 for an argument error. The threshold is inclusive: --warn exits 1 at 70%, including exactly 70%. A missing window counts as zero for threshold checks. JSON is the raw payload, so its shape depends on the source; plain and short output normalize both.

📟 Claude Code status line

Set statusLine in ~/.claude/settings.json (merge this field into your existing settings):

{
  "statusLine": {"type": "command", "command": "claude-usage --statusline"}
}

Claude Code pipes its documented status JSON to the command on each repaint:

Fable 5.1 · 5h 25% · 7d 59%

Missing parts are omitted. This mode never looks up credentials or makes a network call. It also writes last-statusline.json, feeding the documented fallback when the endpoint is unavailable. Invalid input produces no output and exits 0. claude-usage --format short gives the same compact format from the normal source order; endpoint answers usually have no model, so show 5h 23% · 7d 59%.

🤔 How it works

Sources are tried in this order:

1. last-usage.json if less than 5 minutes old.
2. One live GET https://api.anthropic.com/api/oauth/usage, saved on success.
3. last-usage.json if less than 60 minutes old.
4. last-statusline.json if less than 60 minutes old and it has rate_limits.

Both caches live in ~/.claude, or CLAUDE_CONFIG_DIR when set. Cache writes are atomic. Cached answers at least a minute old show their source and age, e.g. (from the endpoint, 3 min ago); status-line answers always show their age. If every source fails, the distinct reasons appear once each on stderr.

The endpoint returns HTTP 429 on back-to-back calls, sometimes blocking for minutes. Five-minute reuse avoids repeating requests; there are no retries or polling, and the single request times out after 15 seconds.

🔒 Privacy & security

• Reads existing credentials only; never refreshes or writes credentials.
• Sends the token only to api.anthropic.com, with the usage request.
• Writes only the two local usage caches; never modifies Claude Code settings.
• Never prints secrets or headers, including with -v.
• No telemetry. No third-party calls.

⚠️ Good to know

• The OAuth usage endpoint is undocumented and rate limited; it may change or disappear. The documented status-line path is the fallback.
• Status-line rate_limits for subscription windows is Pro/Max only, appears after the first API response, and drops individual windows after they reset. It updates only while a Claude Code session is active and repainting.
• The observed endpoint response came from a Max account. Fields on other plans may differ; an API key is not a Claude Code OAuth login.
• Any running claude keeps the access token fresh. This tool deliberately does not implement the undocumented refresh flow.
• Use /feedback in Claude Code to ask Anthropic for an official claude usage command.

🛠️ Install options

pip install claude-usage-limits       # from PyPI
pipx install claude-usage-limits      # isolated command installation
pip install .                  # from a local clone

Requires Python 3.9+. The PyPI distribution is claude-usage-limits; the command and GitHub repo are claude-usage, and the import package is claude_usage. The PyPI names claude-usage, claude-usage-cli, and claude-code-usage belong to unrelated projects.

🤝 Contributing

Issues and PRs are welcome. After installing the local project with pip install -e ., run the tests with:

pip install pytest && pytest -q

Tests use temporary config directories and mocked HTTP; they never contact the endpoint or read your real credentials.

📄 License

MIT — do whatever you like.