usage

Probe Anthropic rate-limit headers and output remaining quota percentages.

5|1|Updated Apr 14, 2026
One-click install
npx skills add https://github.com/dburkart/auto-engineer --skill usage-dburkart
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: usage
Source: https://github.com/dburkart/auto-engineer/tree/main/.claude/skills/usage
Command: npx skills add https://github.com/dburkart/auto-engineer --skill usage-dburkart

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires bash, curl, python3, stat, mktemp, python3 modules (json,re,time), and includes scripts (resource) components.

What problem does it solve?

This Skill answers whether your Claude Code session is currently allowed, warning, or rejected by reporting real session-quota usage for the 5-hour and 7-day windows.

Core Features & Use Cases

  • Quota probe using Anthropic rate-limit headers: Reads anthropic-ratelimit-unified-* response headers via a minimal 1-token request, matching what Claude Code’s statusline reports.
  • Cached, low-cost repeated checks: Caches the probe result for 60 seconds to avoid unnecessary calls, with a --force option to bypass the cache.
  • Structured output for automation: Emits machine-readable lines (remaining_pct, reset_ts) before a human summary, supporting both manual questions and auto-engineer quota gating.
  • Fallback estimation when probing fails: Uses ccusage to estimate blocks and remaining time when the direct probe cannot retrieve headers, clearly labeling results as estimated.

Quick Start

Run the command bash .claude/skills/usage/probe.sh to get your current 5h and 7d quota utilization, reset times, and status.

Frequently Asked Questions about usage

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check my Claude Code session quota and rate limits?

You can check your Claude Code session quota by probing the Anthropic /v1/messages endpoint and parsing the anthropic-ratelimit-unified response headers for 5-hour and 7-day usage windows.

What's the best way to get exact remaining quota percentage for Claude Code automation?

The best way to get exact remaining quota is making a minimal 1-token request to Anthropic's API and reading the ratelimit-unified headers, which outputs a machine-readable remaining_pct and reset_ts format.

Why does my Claude Code rate limit probe fail and how can I estimate usage instead?

Rate limit probing fails when headers cannot be retrieved from the API response, in which case you can fall back to using ccusage to estimate session blocks and remaining time, clearly labeling results as estimated.

Can I cache Claude Code quota checks to avoid hitting API rate limits?

Yes, you can cache quota probe results for 60 seconds to avoid unnecessary API calls, with a --force option available to bypass the cache and retrieve fresh rate limit data.

Do I need credentials access to check Claude Code quota status?

Yes, checking Claude Code quota status requires credential access from ~/.claude/.credentials.json to authenticate the probe request to the Anthropic API.

What dependencies are needed to run a Claude Code quota probe script?

Running a Claude Code quota probe requires bash, curl, python3 with json/re/time modules, stat, and mktemp to execute the script and parse rate limit headers.