170 lines
4.1 KiB
Markdown
170 lines
4.1 KiB
Markdown
# 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)
|