# Claude Usage Waybar Module

A custom Waybar module that displays your Claude API usage with percentage differences comparing your usage rate to the position in the time window.

## Features

- Displays weekly (7-day) and session (5-hour) usage limits
- Shows percentage differences indicating if you're using more (+) or less (-) than the expected rate
- Simple text-only display format
- No external dependencies - uses only Python built-in libraries

## Requirements

- Python 3.8+
- Claude Code CLI installed and authenticated
- Waybar

## Installation

1. Clone or download this repository
2. Make the script executable:
   ```bash
   chmod +x claude_usage_waybar.py
   ```

3. Ensure you have Claude Code CLI installed and authenticated:
   ```bash
   claude --version
   ```

## Usage

### Testing the Script

Run the script directly to see the output:

```bash
./claude_usage_waybar.py
```

Expected output:
```json
{"text": "W: +5.2% | S: -3.1%", "tooltip": "Weekly: 18.5% used (13.3% through week) = +5.2%\nSession: 25.0% used (28.1% through 5h) = -3.1%\n\nWeekly resets: 2026-01-15 12:00\nSession resets: 2026-01-10 18:00", "class": "claude-usage", "percentage": 18}
```

### Waybar Configuration

Add to your `~/.config/waybar/config`:

```json
{
  "modules-right": ["custom/claude-usage", "other-modules..."],

  "custom/claude-usage": {
    "exec": "/path/to/claude_usage_waybar.py",
    "return-type": "json",
    "interval": 120,
    "format": "{}"
  }
}
```

Replace `/path/to/claude_usage_waybar.py` with the actual path to the script.

### Optional Styling

Add to `~/.config/waybar/style.css`:

```css
#custom-claude-usage {
  padding: 0 10px;
  color: #ffffff;
}

#custom-claude-usage.claude-usage-error {
  color: #ff6b6b;
}
```

### Reload Waybar

After updating the configuration:

```bash
killall -SIGUSR2 waybar
```

## Understanding the Display

### Text Format

`W: +5.2% | S: -3.1%`

- **W**: Weekly (7-day) usage difference
- **S**: Session (5-hour) usage difference
- **+**: Using more than expected at this point in the time window
- **-**: Using less than expected

### Interpretation

If the display shows `W: +5.2%`:
- You've used 18.5% of your weekly quota
- You're 13.3% through the 7-day window
- Difference: 18.5% - 13.3% = +5.2%
- This means you're using more than the average rate would predict

If the display shows `S: -3.1%`:
- You've used 25.0% of your session quota
- You're 28.1% through the 5-hour window
- Difference: 25.0% - 28.1% = -3.1%
- This means you're using less than the average rate would predict

### Tooltip

Hover over the module to see detailed information:
- Actual usage percentages
- Time elapsed percentages
- Reset times for both limits

## Troubleshooting

### "No creds" Error

The script cannot find Claude Code credentials. Ensure:
1. Claude Code CLI is installed
2. You've authenticated: `claude auth login`
3. Credentials file exists at `~/.claude/.credentials.json`

### "Auth failed" Error

The OAuth token is expired or invalid. Re-authenticate:

```bash
claude auth logout
claude auth login
```

### "API error" Error

Failed to fetch usage data from the Anthropic API. Check:
1. Internet connection
2. Anthropic API status
3. API endpoint accessibility

### "Timeout" Error

Request to the API timed out. This may indicate:
- Slow internet connection
- API performance issues
- Network firewall blocking the request

## How It Works

1. **Read Credentials**: Extracts OAuth access token from `~/.claude/.credentials.json`
2. **Fetch Usage**: Makes authenticated GET request to `https://api.anthropic.com/api/oauth/usage`
3. **Calculate Differences**: Compares usage percentage to time elapsed percentage
4. **Format Output**: Returns JSON in Waybar-compatible format

## Technical Details

- **No caching**: Fetches fresh data on every execution
- **Request timeout**: 10 seconds
- **Recommended interval**: 120-300 seconds
- **Built-in libraries only**: `urllib`, `json`, `datetime`, `pathlib`

## References

- [Waybar Custom Module Documentation](https://github.com/Alexays/Waybar/wiki/Module:-Custom)
- [Claude Code CLI Documentation](https://code.claude.com/docs)