claude-usage

What This Skill Does

The Claude Usage Checker skill for OpenClaw provides a seamless interface for monitoring your Claude Code or Claude Max API utilization. As an AI agent user, you often operate within specific rate limits or quota caps. This skill automates the process of querying the official Claude CLI to retrieve real-time data regarding your current consumption, helping you stay productive without hitting unexpected barriers. By interacting with the CLI through a PTY (pseudo-terminal), the skill captures your usage statistics and parses them into a human-readable table, showing exactly how much of your quota remains for the current week and for specific models.

Installation

To integrate this utility, ensure you have the OpenClaw agent runtime installed. Run the command clawhub install openclaw/skills/skills/aligurelli/claude-usage-checker in your terminal. Note that this skill depends on the claude-code npm package. You must have the Claude CLI installed globally (npm i -g @anthropic-ai/claude-code) and have completed the authentication process via your local terminal before the agent can successfully execute the checker. If the agent detects a lack of authentication, it will provide instructions on how to perform the browser-based login flow.

Use Cases

• Proactive Limit Monitoring: Check your usage status before beginning a long coding session or data analysis task.
• Budgeting & Planning: Understand your weekly Sonnet versus general model usage to optimize how you spend your allocated quota.
• Troubleshooting: Identify why the agent might be responding slowly or failing to execute tasks by checking if you have hit a usage cap.

Example Prompts

1. "How much of my Claude usage do I have left for this week?"
2. "Can you check my current Claude quota and see when it resets?"
3. "Am I near my usage limit for the Sonnet model?"

Tips & Limitations

• Reset Times: The skill automatically converts the CLI's raw output into a standard HH:MM format for clarity. Pay close attention to the 'Current week' vs 'Extra usage' rows to differentiate between base limits and paid/overflow usage.
• Latency: Because the skill invokes a local process, allow a few seconds for the Claude CLI to initialize. The agent implements intelligent polling, but slow system performance may impact retrieval speed.
• Auth Requirements: The skill cannot perform browser-based authentication headlessly. If the tool reports 'Missing API key', you must manually run claude in your terminal to complete the OAuth flow.