convez.ai
Skill
BenjaminHolderbein

claude-usage

BenjaminHolderbein/claude-usage

Ver no GitHub
InicialPluginScore · de 0 a 100

Claude Code skill to check your Claude usage limits (5-hour + 7-day windows) from the terminal.

Instalação

$npx convez-ai BenjaminHolderbein/claude-usage

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

claude-usage

A Claude Code skill that reports how much of your Claude (Anthropic) usage limit you've consumed — the rolling 5-hour session window and the 7-day limits — without leaving your terminal.

It reads the same OAuth token Claude Code already stores and queries the same endpoint the built-in /usage command uses, then prints a clean summary:

Claude usage limits
  5-hour session             8%   resets Thu Jun 11, 4:40 PM PDT
  7-day (all models)        15%   resets Mon Jun 15, 12:00 PM PDT
  7-day Opus             not tracked
  7-day Sonnet               0%   resets Mon Jun 15, 12:00 PM PDT
  extra usage            disabled (hard stop at limit)

Why

Claude Code ships a /usage slash command, but it only works inside an interactive session. This packages the same data as:

  • a skill, so you can just ask Claude "where am I on my usage?" and it answers, and
  • a plain script you can run from any shell, drop in a status bar, or wire into automation.

Requirements

  • macOS — the script reads the OAuth token from the login Keychain (service Claude Code-credentials). On Linux the token lives in ~/.claude/.credentials.json instead; see Linux below.
  • Claude Code, signed in at least once.
  • python3 and curl (both present by default on macOS).

Install

Clone anywhere, then symlink it into your Claude Code skills directory so the skill is discoverable:

git clone https://github.com/BenjaminHolderbein/claude-usage.git
ln -s "$(pwd)/claude-usage" ~/.claude/skills/claude-usage

That's it — Claude Code picks up the skill on next launch.

Usage

As a skill, just ask in any Claude Code session:

where am I on my usage limit?

Or run the script directly:

bash ~/.claude/skills/claude-usage/usage.sh          # human-readable summary
bash ~/.claude/skills/claude-usage/usage.sh --json   # raw JSON

Use cases

  • Quick check — "where am I on my usage?" / "am I close to my limit?"

  • Budget a session against your limit. Tell Claude how much of your usage to spend and let it self-govern:

    • "Use 10% of my limit thinking this through."
    • "Spend up to a quarter of my usage on this refactor."
    • "Use my whole limit — go as deep as you can."

    The skill reads your current 5-hour utilization to set a ceiling (current + N%), works in chunks, re-polls between them, and keeps going until the meter actually reaches the budget (it also watches the 7-day limit, since that's the harder wall). The reported percentage is the same number Anthropic's official usage page shows — verified by reading both side by side while burning tokens — so Claude steers by a real meter, not a guess. Its only limit is 1-point resolution (the same as the official UI), which is plenty for a "spend N%" budget.

How it works

  1. Pulls your OAuth access token from the macOS Keychain.
  2. GET https://api.anthropic.com/api/oauth/usage with that token and the anthropic-beta: oauth-2025-04-20 header.
  3. Formats the utilization / resets_at fields for each limit window into a table, converting reset timestamps to your local time zone.

It is strictly read-only — it never writes or mutates anything.

Response fields

Each window is a bucket with utilization (0–100 percent) and resets_at (ISO 8601). Notable keys:

FieldMeaning
five_hourRolling 5-hour session window.
seven_day7-day rolling limit across all models.
seven_day_opus / seven_day_sonnetPer-model 7-day buckets. Often null (not separately tracked).
extra_usageOverage billing. is_enabled: false means usage hard-stops at the limit instead of spilling into paid credits.

Linux

The script reads the Keychain, which is macOS-only. On Linux the token is in ~/.claude/.credentials.json; swap the token line for:

TOKEN=$(python3 -c "import json,os; print(json.load(open(os.path.expanduser('~/.claude/.credentials.json')))['claudeAiOauth']['accessToken'])")

Caveats

  • The usage endpoint is undocumented and used internally by Claude Code; it could change without notice.
  • If the API returns 401, your access token has expired — Claude Code refreshes it the next time you launch it.

License

MIT © 2026 Benjamin Holderbein

Ver o original no GitHub

Bom para

Relacionados