claude-code-usage

name	claude-code-usage
description	Check Claude Code OAuth usage limits (session & weekly quotas). Use when user asks about Claude Code usage, remaining limits, rate limits, or how much Claude usage they have left. Includes automated session refresh reminders and reset detection monitoring.
metadata	{"clawdbot":{"emoji":"📊","os":["darwin","linux"],"requires":{"bins":["curl"]}}}

Claude Code Usage

Check your Claude Code OAuth API usage limits for both session (5-hour) and weekly (7-day) windows.

Quick Start

cd {baseDir}
./scripts/claude-usage.sh

Usage

# Default: show cached usage (if fresh)
./scripts/claude-usage.sh

# Force refresh from API
./scripts/claude-usage.sh --fresh

# JSON output
./scripts/claude-usage.sh --json

# Custom cache TTL
./scripts/claude-usage.sh --cache-ttl 300

Output

Text format (default):

🦞 Claude Code Usage

⏱️  Session (5h): 🟢 ████░░░░░░ 40%
   Resets in: 2h 15m

📅 Weekly (7d): 🟡 ██████░░░░ 60%
   Resets in: 3d 8h

JSON format (--json):

{
  "session": {
    "utilization": 40,
    "resets_in": "2h 15m",
    "resets_at": "2026-01-19T22:15:00Z"
  },
  "weekly": {
    "utilization": 60,
    "resets_in": "3d 8h",
    "resets_at": "2026-01-22T04:00:00Z"
  },
  "cached_at": "2026-01-19T20:00:00Z"
}

Features

• 📊 Session limit (5-hour window) - Short-term rate limit
• 📅 Weekly limit (7-day window) - Long-term rate limit
• ⚡ Smart caching - 60-second cache to avoid API spam
• 🎨 Beautiful output - Progress bars, emojis, color-coded status
• 🔄 Force refresh - --fresh flag to bypass cache
• 📤 JSON output - Machine-readable format
• 🔔 Automated monitoring - Get notified when quotas reset

Status Indicators

• 🟢 Green - 0-50% usage (healthy)
• 🟡 Yellow - 51-80% usage (moderate)
• 🔴 Red - 81-100% usage (high/critical)

Requirements

• macOS: Uses Keychain to access Claude Code credentials
• Linux: Uses secret-tool for credential storage
• Credentials: Must have Claude Code CLI authenticated

How It Works

1. Retrieves OAuth token from system keychain
2. Queries api.anthropic.com/api/oauth/usage with OAuth bearer token
3. Parses five_hour and seven_day utilization metrics
4. Calculates time remaining until reset
5. Formats output with progress bars and status indicators
6. Caches result for 60 seconds (configurable)

Cache

Default cache: /tmp/claude-usage-cache (60s TTL)

Override:

CACHE_FILE=/tmp/my-cache CACHE_TTL=300 ./scripts/claude-usage.sh

Examples

Check usage before starting work:

./scripts/claude-usage.sh --fresh

Integrate with statusline:

usage=$(./scripts/claude-usage.sh | grep "Session" | awk '{print $NF}')
echo "Session: $usage"

Get JSON for monitoring:

./scripts/claude-usage.sh --json | jq '.session.utilization'

Automated Monitoring

Session Refresh Reminders (Recommended)

Get notified exactly when your 5-hour session quota refreshes!

Quick Setup:

./scripts/session-reminder.sh

This creates a self-scheduling chain of cron jobs that:

1. Checks your current session expiry time
2. Schedules the next reminder for when your session refreshes
3. Notifies you with current usage stats
4. Auto-removes itself (the new cron takes over)

What You'll Get:

🔄 Claude Code Session Status

⏱️  Current usage: 44%
⏰ Next refresh: 2h 15m

Your 5-hour quota will reset soon! 🦞

✅ Next reminder scheduled for: Jan 22 at 01:22 AM

How It Works:

• Each reminder runs claude-usage.sh to find the exact session reset time
• Schedules a one-time cron for that exact moment
• Repeats every 5 hours automatically
• Self-correcting if session times ever drift

Benefits:

• ✅ Accurate to the minute
• ✅ No manual scheduling needed
• ✅ Adapts to your actual usage patterns
• ✅ Minimal API calls (only when needed)

Reset Detection Monitor (Alternative)

Get automatic notifications when your Claude Code quotas reset by polling usage.

Quick Setup:

# Test once
./scripts/monitor-usage.sh

# Setup automated monitoring (runs every 30 minutes)
./scripts/setup-monitoring.sh

Or add via Clawdbot directly:

# Check every 30 minutes
clawdbot cron add --cron "*/30 * * * *" \
  --message "cd /Users/ali/clawd/skills/claude-code-usage && ./scripts/monitor-usage.sh" \
  --name "Claude Code Usage Monitor" \
  --session isolated --deliver --channel telegram

What You'll Get:

🎉 Claude Code Session Reset!

⏱️  Your 5-hour quota has reset
📊 Usage: 2%
⏰ Next reset: 4h 58m

Fresh usage available! 🦞

How It Works:

1. Monitors usage every 30 minutes (configurable)
2. Detects resets when usage drops significantly (>10% or <5%)
3. Sends notifications via Telegram when resets occur
4. Tracks state in /tmp/claude-usage-state.json

Customization:

# Change check interval
clawdbot cron add --cron "*/15 * * * *" ...  # Every 15 minutes
clawdbot cron add --cron "0 * * * *" ...      # Every hour

# Custom state file location
STATE_FILE=/path/to/state.json ./scripts/monitor-usage.sh

Which Monitoring Method?

Feature	Session Reminder	Reset Detection
Accuracy	✅ Exact minute	~30min window
API calls	Minimal	Every check
Notification timing	Right on reset	Up to 30min delay
Setup	One command	One command
Maintenance	Self-scheduling	Cron runs forever

Recommendation: Use Session Reminder for precise, real-time notifications.

Troubleshooting

No credentials found:

• Ensure Claude Code CLI is installed and authenticated
• Run claude once to trigger OAuth flow

API request failed:

• Check internet connection
• Verify OAuth token hasn't expired
• Try --fresh to force new request

Linux users: Install libsecret for credential storage:

# Debian/Ubuntu
sudo apt install libsecret-tools

# Fedora/RHEL
sudo dnf install libsecret