agentleFS
pionion-aipionion-ai/quotabar/.claude/skills/claude-usage/SKILL.md

claude-usage

Skill0 starsChanged 4 months agoMITView on GitHub

Check how much of the Claude Code subscription is left, when limits reset, estimated per-model token headroom, and Anthropic API spend — via the local claude-usage tool (claude_usage.py). Use this skill whenever the user asks "how much usage / quota / credits do I have left", "am I close to my limit", "when does my limit reset", "how many tokens can I still use", "what's my Claude Code usage", "how much have I spent on the API", or wants this reported on a schedule / as a cron job. Trigger even when phrased loosely ("am I about to run out?", "check my limits") — prefer running this tool over guessing, since the numbers are live.

  • Reads credentials

6 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions6 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 6

    1. tdimino/claude-code-minoan★ 41same name
    2. thaitype/skills★ 13same name
    3. jakeonrails/claude-usage★ 1same name
    4. BenjaminHolderbein/claude-usage★ 0same name
    5. lucasmocellin/claude-skills★ 0same name
    6. stv-io/claude-skills★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read these distinctions back to the user — they're easy to conflate:

    line 49
  2. Distinctive:

    Never print the key, never commit it, and never paste it into chat output.

    line 85

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

claude-usage

A small, dependency-free Python tool that reports Claude Code subscription usage limits, reset times, per-model token headroom, and Anthropic API spend. Prefer running it over answering from memory — the figures are live and change constantly.

Where it lives

claude_usage.py at the repo root. It's executable and needs only Python 3.9+ (standard library). Run it with an absolute path if the working directory is elsewhere.

How to run it

Pick the flag that matches what the user asked. Default (no flags) answers the common "how much is left / when does it reset" question.

User wants…Command
Current usage % + reset times./claude_usage.py
Machine-readable output (for scripts/cron)./claude_usage.py --json
The complete raw API payload./claude_usage.py --raw
Per-model token headroom estimate./claude_usage.py --estimate
Anthropic API spend (needs Admin key)./claude_usage.py --api-credits
Everything together./claude_usage.py --estimate --api-credits
Alert when a window crosses a threshold./claude_usage.py --threshold 85

--days N sets the API-spend window for --api-credits (default 30). --threshold N makes the tool exit 1 when any window is ≥ N% used — use it for cron/launchd alerting. Exit codes: 0 ok, 1 threshold breached, 2 error.

What each number means

Read these distinctions back to the user — they're easy to conflate:

  • Subscription windows (five_hour, seven_day, per-model weekly) report % used / % left and an ISO reset time. The 5-hour window is usually the binding one. This is the answer to "how much usage do I have left."
  • Extra-usage credits = pay-as-you-go overflow on the subscription. If extra_usage is absent/disabled, the user has none — once subscription limits are hit, work stops. They enable or buy these with /usage-credits inside Claude Code (formerly /extra-usage).
  • API console credits (console.anthropic.com prepaid balance) are a separate billing account. --api-credits shows consumed API spend via the Admin API — it is not a remaining-balance figure. No public endpoint exposes the remaining prepaid balance; that's only in console Billing.

The token estimate is approximate — say so

--estimate recovers each window's budget from local session logs: it measures what was actually spent in the window, treats that as utilization% of the budget, backs out the total, and converts the remainder to tokens per model at API list prices (the subscription discount cancels, so the result is discount-independent). When utilization is low the back-out amplifies noise, so present these as order-of-magnitude, and note output tokens are the scarce side (cached input is far cheaper, so real headroom is higher).

The model list is read live from /v1/models; prices come from pricing.json (edit that file when prices change — don't hardcode model names in code). The output's models_source says live_api or pricing_config (the fallback when the API is unreachable).

Credentials

  • Subscription data uses the local Claude Code OAuth token (macOS Keychain or ~/.claude/.credentials.json) — no setup. A 401 means the token expired; tell the user to run claude once to refresh.
  • --api-credits needs an Anthropic Admin key (sk-ant-admin…), read from ANTHROPIC_ADMIN_KEY or the gitignored .secrets file. Never print the key, never commit it, and never paste it into chat output.

Scheduling

For a recurring check, wire the --threshold form into cron or launchd and act on the exit code / --json output. Example cron line:

*/30 * * * * /path/to/quotabar/claude_usage.py --threshold 85 >> ~/claude-usage.log 2>&1

See README.md for full details.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.