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

Retrieves OAuth token from system keychain
Queries
```
api.anthropic.com/api/oauth/usage
```
with OAuth bearer token
Parses
```
five_hour
```
and
```
seven_day
```
utilization metrics
Calculates time remaining until reset
Formats output with progress bars and status indicators
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:

Checks your current session expiry time
Schedules the next reminder for when your session refreshes
Notifies you with current usage stats
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:

Monitors usage every 30 minutes (configurable)
Detects resets when usage drops significantly (>10% or <5%)
Sends notifications via Telegram when resets occur
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

Claude Code Usage

AI Skill Market Insights

Be Part of the 0+ Developer Community