# Check Usage

> Check Claude's current rate-limit utilization and decide whether to pause the task. Use before starting an unusually expensive step of a long-running task, when the usage-limit hook is not installed, or when the user asks where the budget stands.

- Skill: `jgjake2/check-usage` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jgjake2/check-usage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jgjake2/check-usage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- Author: jgjake2 (https://skillmd.com/u/jgjake2)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jgjake2/check-usage

---


# check-usage

```
node .claude/skills/check-usage/check-usage.js
```

Prints a single JSON object to stdout.

**If the PreToolUse usage-limit hook is installed in this project, checking is already automatic**
(every 10 minutes, after a task has run 30 minutes). Do not poll this on a timer as well --
each check makes a real API call upstream.

## Response

| Field | Meaning |
|---|---|
| `band` | `ok`, `warn`, `grace`, `stop`, or `unknown` |
| `shouldStop` | `true` only for `stop` |
| `degraded` | `true` when the reading is unavailable OR only partly understood -- unknown, not safe |
| `reason` | One-line summary including any caveats |
| `windows` | Every limit window reported, each with `utilization` (0-1), `percent`, `resetsAt` |
| `highest` | The window closest to its limit -- this drives the verdict |
| `grace` | When banded `grace`: which window, when it resets, how long until then |
| `unreadableWindows` | Windows whose utilization could not be parsed; non-empty means the verdict is partial |
| `ignoredWindows` | Windows skipped because their `status` marks them inapplicable |
| `configIssues` | Threshold/env problems; non-empty means defaults were substituted |

## How to act on it

- **`ok`** -- continue normally.
- **`warn`** (>=80%) -- finish the current step; do not *begin* a large new one. Consider a
  checkpoint via `save-progress`. Advisory only.
- **`grace`** -- past the stop threshold, but the limiting window resets within 10 minutes.
  **Keep working.** Do not halt and do not checkpoint for this. Avoid starting a large step
  until after `grace.resetsAt`.
- **`stop`** (>=90% with no imminent reset, or >=98% regardless) -- halt. Write up the work
  so far and a concrete resume plan, save both with `save-progress`, then stop and tell the
  user how to resume.
- **`unknown`** / `degraded: true` -- **keep working**. Never treat a missing reading as a
  reason to stop, and never assume usage is low. Mention it to the user once.

## Notes

- Exit code is always 0 when the check ran. A non-zero exit means the script itself broke.
- All limit windows are read generically, so a separate Opus weekly cap is picked up without
  a code change.
- Thresholds are set as **fractions** (`0.9`, not `90`) via `USAGE_LIMIT_STOP_AT`,
  `USAGE_LIMIT_WARN_AT`, `USAGE_LIMIT_HARD_STOP_AT`, and `USAGE_LIMIT_RESET_GRACE_MS`. An out-of-range value
  falls back to the default and is reported in `configIssues` rather than silently disabling
  the check.