home / skills / openclaw / skills / claude-usage-checker

claude-usage-checker skill

This skill reports your Claude Code and Claude Max usage by launching the Claude CLI and extracting quota details for quick planning.

npx playbooks add skill openclaw/skills --skill claude-usage-checker

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.1 KB

---
name: claude-usage
description: Check Claude Code / Claude Max usage limits. Run when user asks about usage, limits, quota, or how much Claude capacity is left.
homepage: https://github.com/aligurelli/clawd
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["claude"], "pty": true }
      }
  }
---

# Claude Usage Checker

Launches the Claude CLI interactively (PTY) and reads the `/usage` output to report your Claude Code / Claude Max quota.

## Prerequisites
- **Claude CLI** must be installed (`npm i -g @anthropic-ai/claude-code`) and logged in
- If running `claude` shows "Missing API key", the user must log in manually first: open a terminal, run `claude`, and complete the browser login flow
- Requires an interactive PTY — the agent will launch a local process and read its output (quota info only)

## Steps

1. Launch `claude` with PTY
2. Wait for the welcome screen (poll until it appears)
3. Send `/usage` + Enter
4. Read the output (poll until usage data appears)
5. Close with Escape then `/exit`
6. Report the results

## Commands

```bash
# Launch claude with PTY
exec pty=true command="claude"

# Wait and check log
process action=poll sessionId=XXX timeout=5000

# Send /usage
process action=send-keys sessionId=XXX literal="/usage"
process action=send-keys sessionId=XXX keys=["Enter"]

# Read output
process action=poll sessionId=XXX timeout=5000

# Exit
process action=send-keys sessionId=XXX keys=["Escape"]
process action=send-keys sessionId=XXX literal="/exit"
process action=send-keys sessionId=XXX keys=["Enter"]
```

## Notes
- If you see "Missing API key" → tell the user to log in; browser-based login won't work headlessly
- Allow a few seconds between polls — Claude CLI starts slowly
- "Current week" = weekly reset, not daily

## Output Format

Report in a table:

| | Usage | Resets |
|---|---|---|
| **Current session** | X% used | today at HH:MM (timezone) |
| **Weekly (all models)** | X% used | HH:MM (timezone) |
| **Weekly (Sonnet only)** | X% used | HH:MM (timezone) |
| **Extra usage** | X% used / $X of $Y spent | date (timezone) |

Always show reset times. The CLI displays them as "Resets Xpm" — convert to HH:MM format.

Overview

This skill checks Claude Code and Claude Max usage and reports quota details from the Claude CLI. It launches the local claude CLI in an interactive PTY, runs the /usage command, and parses the output into a clear usage summary with reset times. It’s designed to give fast, actionable visibility into session, weekly, model-specific, and extra usage.

How this skill works

The skill spawns an interactive claude process (PTY), waits for the CLI welcome screen, sends the /usage command, and polls the process output until usage information appears. It extracts usage percentages, dollar amounts, and reset strings, converts reset times to HH:MM in the local timezone, and returns a concise table of current session, weekly (all models), weekly (Sonnet only), and extra usage. If the CLI reports a missing API key, the skill stops and instructs the user to log in interactively.

When to use it

You want to know remaining Claude Code / Claude Max quota before starting heavy work.
You need weekly or session-level usage percentages and reset times.
You want model-specific usage (Sonnet) or extra paid usage details.
You suspect quota limits are blocking new Claude jobs and need confirmation.
You need a quick CLI-based check when no API-based usage endpoint is available.

Best practices

Ensure the claude CLI is installed and you are logged in locally before running the skill.
Run the check from a machine that allows interactive terminal sessions (PTY).
Allow a few seconds for the CLI to start and for the usage screen to populate.
If the CLI shows "Missing API key", log in via the browser on that machine and retry.
Run checks near the expected reset time if you need precise remaining-window planning.

Example use cases

Confirm remaining weekly Claude usage before launching a long batch of queries.
Verify Sonnet-specific consumption to decide whether to switch models for cost reasons.
Check extra paid usage and dollars spent to reconcile billing or usage alerts.
Share a quick usage snapshot with teammates before scheduling heavy model runs.

FAQ

What if I see "Missing API key" when the skill runs?

Open a terminal on the same machine, run the claude CLI, and complete the browser-based login flow. Headless login is not supported.

Does this skill change any account settings?

No. It only launches the claude CLI, sends /usage, reads output, and exits. It does not modify configuration or quotas.

How are reset times shown?

Reset strings from the CLI (e.g., "Resets Xpm") are converted to HH:MM in the local timezone and included for every reported row.