claude-code-usage

# Claude Code Usage

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

## Quick Start

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

## Usage

```bash
# 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`):
```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:
```bash
CACHE_FILE=/tmp/my-cache CACHE_TTL=300 ./scripts/claude-usage.sh
```

## Examples

**Check usage before starting work:**
```bash
./scripts/claude-usage.sh --fresh
```

**Integrate with statusline:**
```bash
usage=$(./scripts/claude-usage.sh | grep "Session" | awk '{print $NF}')
echo "Session: $usage"
```

**Get JSON for monitoring:**
```bash
./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:**
```bash
./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:**
```bash
# Test once
./scripts/monitor-usage.sh

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

Or add via Clawdbot directly:
```bash
# 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:**
```bash
# 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:
```bash
# Debian/Ubuntu
sudo apt install libsecret-tools

# Fedora/RHEL
sudo dnf install libsecret
```