- name
- claude-usage
- description
- Check Claude Max plan usage limits by launching Claude Code and running /usage. Use when the user asks about Claude plan usage, remaining quota, rate limits, or sends /claude_usage.
Claude Usage
Check Claude Max subscription usage by launching Claude Code interactively.
Requirements
expectmust be installed (available at/usr/bin/expecton macOS)- Claude Code CLI must be installed and authenticated
Procedure
Use expect to automate the interactive TUI (the /usage command is a terminal UI, not a simple CLI):
- Run the expect script to launch Claude Code and execute
/usage:
expect -c '
spawn claude
expect "Welcome"
send "/usage\
"
expect "Show plan usage"
sleep 1
send "\
"
expect "Resets"
'- Parse the output for these metrics:
- Current session: Look for "Current session" line with percentage and reset time - Current week (all models): Look for "Current week (all models)" with percentage and reset date - Current week (Sonnet only): Look for "Current week (Sonnet only)" with percentage - Extra usage: Look for "Extra usage" line
- Strip ANSI escape codes from output before parsing
- Format and relay the metrics to the user
Example Output
The expect script returns something like:
Current session ██████████░░░░░░░░░░░░░░░░░ 21% used Resets 5:59pm (America/Los_Angeles)
Current week (all models)
████████████████████████░░░░░░░░░░░░░ 28% used Resets Feb 21 at 6am (America/Los_Angeles)
Current week (Sonnet only)
█████████████████████████░░░░░░░░░░░░ 29% used Resets Feb 21 at 7am (America/Los_Angeles)
Extra usage
Extra usage not enabled • /extra-usage to enable
$50 free extra usage · /extra-usage to enableFallback
If expect is not available, fall back to:
claude auth status- shows subscription type (Max/Pro)~/.claude/stats-cache.json- shows local session token counts (limited data)