stv-iostv-io/claude-skills/skills/claude-usage/SKILL.md

claude-usage

Skill0 starsChanged 2 days agoMITView on GitHub

Check the user's Claude plan usage (needs a one-line status-line hook, set up once) — the 5-hour session limit and the 7-day weekly limit (percent used, time to reset). Use for "/claude-usage", "how much usage do I have left", "what's my session usage", "when does my limit reset", "am I close to the limit", and BEFORE launching anything expensive (workflows, fan-outs of many subagents) to decide whether there is headroom.

6 other projects use a version of this.

Adopted by

Most recently taken up by

jakeonrails/claude-usagetheir own version, first seen Aug 12, 2026
pionion-ai/quotabartheir own version, first seen Aug 4, 2026
BenjaminHolderbein/claude-usagetheir own version, first seen Jun 13, 2026
tdimino/claude-code-minoantheir own version, first seen Apr 16, 2026
lucasmocellin/claude-skillstheir own version, first seen Apr 12, 2026
thaitype/skillstheir own version, first seen Mar 15, 2026

Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
tdimino/claude-code-minoan★ 41same name
thaitype/skills★ 13same name
jakeonrails/claude-usage★ 1same name
BenjaminHolderbein/claude-usage★ 0same name
lucasmocellin/claude-skills★ 0same name
pionion-ai/quotabar★ 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.
In this repository7 other files it gives its agents.
- browser-selectSkill
- diagram-styleSkill
- docs-sweepSkill
- mac-disk-cleanupSkill
- md-tocSkill
- session-exportSkill
- tracker-pageSkill

The file

We split this skill into the rules it gives an agent

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

0
Common
Most of the 4 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Run the CLI; don't estimate usage from memory or from this conversation's length.
line 8
Very specific:
Before an expensive run: if five_hour.used_percentage ≥ 80 or seven_day.used_percentage ≥ 90, tell the user the headroom and the reset time …
line 39

“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 plan usage

Run the CLI; don't estimate usage from memory or from this conversation's length. It is bin/claude-usage in this skill's folder; if claude-usage isn't on your PATH, run it by that full path.

claude-usage          # human-readable
claude-usage --json   # structured, for decisions

--json shape:

{
  "five_hour": { "used_percentage": 44, "resets_at": 1790341800, "resets_in_seconds": 6900 },
  "seven_day": { "used_percentage": 54, "resets_at": 1790499600, "resets_in_seconds": 164700 },
  "captured_at": 1790334860, "age_seconds": 12, "stale": false
}

A window is null when no live reading exists (e.g. the 5h window just rolled over and no session has made a call since).

Exit codes

code	meaning	what to do
0	fresh data	use it
1	no data (cache missing/unreadable), or jq missing	say so and point to the setup in the skill's README; don't guess
2	stale (> 5 min old; override with `CLAUDE_USAGE_STALE_SECS`)	still printed; report it with its age

Reading it

Limits are account-wide, shared by every running session and subagent — not per session.
Report both windows with reset times, e.g. "5h: 44%, resets 15:10 · 7d: 54%, resets Sun 11:00". The human output already uses local time; report it in the user's timezone.
Before an expensive run: if five_hour.used_percentage ≥ 80 or seven_day.used_percentage ≥ 90, tell the user the headroom and the reset time and ask before launching. Otherwise just mention the numbers.

How it works (for troubleshooting)

Your status-line command pipes its JSON input into bin/claude-usage-capture, which receives rate_limits from Claude Code on every status-line refresh and merges it into ~/.claude/usage-cache.json: per window, the latest resets_at wins, then the higher used_percentage; expired or missing windows never overwrite good data. This is because many sessions write the file, and idle ones report stale/partial limits.
bin/claude-usage only reads that file.
It updates only while an interactive Claude Code session is open — headless claude -p runs don't run the status line. Stale data usually just means no interactive session is running.

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.

Check your setup, free