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

# Claude Code Usage Skill

Check your Claude Code OAuth API usage limits directly from Clawdbot.

## Features

- 📊 Session (5-hour) and Weekly (7-day) utilization tracking
- 🎨 Beautiful progress bars with color-coded status indicators
- ⚡ Smart caching (60s default) to avoid API spam
- 📤 JSON output for scripting
- 🦞 Telegram-friendly formatting
- 🔔 **NEW v1.1.0**: Automated monitoring with reset notifications

## Quick Test

```bash
cd /Users/ali/clawd/skills/claude-code-usage
./scripts/claude-usage.sh
```

## Example Output

```
🦞 Claude Code Usage

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

📅 Weekly (7d): 🟢 ░░░░░░░░░░ 2%
   Resets in: 6d 21h
```

## Usage in Clawdbot

Just ask:
- "How much Claude usage do I have left?"
- "Check my Claude Code limits"
- "What's my Claude quota?"

The skill automatically triggers and provides a formatted response.

## Automated Monitoring (v1.2.0+)

### Session Refresh Reminders (Recommended)

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

**One-command setup:**
```bash
cd /Users/ali/clawd/skills/claude-code-usage
./scripts/session-reminder.sh
```

This creates a self-scheduling chain that:
- Checks when your session refreshes
- Schedules the next reminder for that exact time
- Notifies you automatically every 5 hours
- Runs forever with zero maintenance

### Reset Detection (Alternative)

Alternatively, monitor for quota resets by polling:

```bash
./scripts/monitor-usage.sh  # Test once
./scripts/setup-monitoring.sh  # Setup automated polling
```

See `SKILL.md` for detailed comparison and configuration options.

## Publishing to ClawdHub

To share with the community:

```bash
cd /Users/ali/clawd/skills
clawdhub publish claude-code-usage \
  --slug claude-code-usage \
  --name "Claude Code Usage" \
  --version 1.0.0 \
  --changelog "Initial release: Session & weekly usage tracking with beautiful formatting"
```

## Author

Created for Clawdbot by RZA 🦞