wlr-claude-usage/README.md

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:

   chmod +x claude_usage_waybar.py
   

3. Ensure you have Claude Code CLI installed and authenticated:

   claude --version
   

Usage

Testing the Script

Run the script directly to see the output:

./claude_usage_waybar.py

Expected output:

{"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:

{
  "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:

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

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

Reload Waybar

After updating the configuration:

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:

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
• Claude Code CLI Documentation