claude-usage

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

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

# 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.