Claude Usage Module for Waybar

A Waybar module that displays Claude AI usage statistics (session %, reset time, weekly %) directly in your status bar.

Features

• 📊 Real-time session usage - See your current 5-hour session percentage
• ⏰ Reset countdown - Know exactly when your session resets
• 📈 Weekly tracking - Monitor your weekly usage limits
• 🎨 Color-coded warnings - Green/Orange/Red based on usage
• 🔄 Dual-mode - Works with Chrome extension (accurate) or standalone (Claude Code only)
• ⚡ Lightweight - Pure bash, no dependencies except jq

Display Format

S13% 4h1m W1%

• S13% - Session usage (13% of 5-hour limit used)
• 4h1m - Time until session resets
• W1% - Weekly usage (1% of weekly limit used)

D45% 23h W8% (Fallback mode without extension)

• D45% - Daily usage (45% of estimated daily limit)
• 23h - Time until midnight reset
• W8% - Weekly usage (8% of estimated weekly limit)

Why Two Modes?

🎯 Recommended: Extension Mode (Accurate)

For accurate, multi-platform tracking, use the Claude Usage Tracker Chrome Extension:

Why? The Anthropic API doesn't expose session limits. The only way to get real session data is from claude.ai/settings/usage.

✅ Tracks ALL usage (web, desktop, mobile) ✅ Shows real session % (not estimates) ✅ Exact reset times from Anthropic's servers ✅ Works even if you don't use Claude Code

📊 Fallback: Standalone Mode (Estimates)

Without the extension, the module uses local Claude Code stats:

⚠️ Only tracks Claude Code usage (not web/mobile) ⚠️ Estimates daily/weekly limits (not session) ⚠️ No reset times (assumes midnight reset) ⚠️ Requires Claude Code to be installed

Bottom line: If you use Claude on multiple platforms or want accurate session tracking, you need the extension. See the extension README for why the API doesn't work for this.

Prerequisites

• Waybar status bar
• jq command-line JSON processor
• Claude Code or Claude web account

Installation

Quick Install

# Download the script
curl -O https://raw.githubusercontent.com/YOUR_USERNAME/omarchy-claude-usage-module/main/claude-usage-status
chmod +x claude-usage-status
sudo mv claude-usage-status /usr/local/bin/

# Add to Waybar config
# See waybar-config-example.jsonc

# Add styling
# See waybar-style-example.css

# Restart Waybar
pkill waybar && waybar &

Manual Installation

1. Copy claude-usage-status to somewhere in your PATH:

   cp claude-usage-status ~/.local/bin/
   chmod +x ~/.local/bin/claude-usage-status

2. Add to your ~/.config/waybar/config.jsonc:

   {
     "modules-left": [
       "custom/omarchy",
       "hyprland/workspaces",
       "custom/claude-usage"
     ],
   
     "custom/claude-usage": {
       "exec": "/home/YOUR_USERNAME/.local/bin/claude-usage-status",
       "return-type": "json",
       "format": "{}",
       "interval": 60,
       "tooltip": true
     }
   }

3. Add styling to ~/.config/waybar/style.css (see waybar-style-example.css)

4. Restart Waybar:

   pkill waybar && waybar &

Configuration

For Accurate Session Data (Recommended)

Install the Claude Usage Tracker Chrome Extension to get accurate session percentages and reset times.

When the extension is active, the module shows: S13% 4h1m W1%

Standalone Mode (Claude Code Only)

Without the extension, the module uses local Claude Code statistics:

• Reads from ~/.claude/stats-cache.json
• Shows daily/weekly estimates: D45% 23h W8%
• Only tracks usage from Claude Code (not web/mobile)

Adjusting Limits

If the percentages don't match your actual limits, edit the script:

# For Pro tier:
daily_limit=500000    # ~500K tokens/day
weekly_limit=4000000  # ~4M tokens/week

# For Max 5x tier:
daily_limit=450000    # ~450K tokens/day
weekly_limit=20000000 # ~20M tokens/week

# For Max 20x tier:
daily_limit=1800000   # ~1.8M tokens/day
weekly_limit=80000000 # ~80M tokens/week

How It Works

1. With Extension: Reads from ~/.cache/claude-usage-web.json (most accurate)
2. Fallback: Reads from ~/.claude/stats-cache.json (Claude Code only)
3. Updates: Every 60 seconds
4. Caching: 1-minute cache to reduce CPU usage

Tooltips

Hover over the module to see detailed information:

With Extension:

Claude Usage (Live from Web)
Session: 13% used
Resets in: 4h1m
Weekly: 1% used

Standalone:

Claude Code (Local Only)
Daily: 45% (225K)
Resets: 23h
Weekly: 8% (351K)

⚠ Open claude.ai/settings/usage for accurate session data

Color Coding

• 🟢 Green (< 70%) - Safe usage levels
• 🟠 Orange (70-89%) - Moderate usage
• 🔴 Red (≥ 90%) - Approaching limit warning

Troubleshooting

Module shows "No Data"

• With extension: Visit claude.ai/settings/usage to populate data
• Without extension: Use Claude Code at least once to create stats file

Percentages seem wrong

• Check your Claude plan tier (Pro/Max 5x/Max 20x)
• Edit script limits to match your tier
• Compare with claude.ai/settings/usage

Not updating

• Check script is executable: ls -l /path/to/claude-usage-status
• Test manually: /path/to/claude-usage-status
• Check Waybar logs: journalctl --user -u waybar -f

Extension data not being used

• Verify file exists: ls -l ~/.cache/claude-usage-web.json
• Check file age: stat ~/.cache/claude-usage-web.json
• Data older than 5 minutes triggers fallback mode

Multi-Device Usage

⚠️ Important: This module only tracks usage on the current machine.

• Using multiple machines? Install on each and check all status bars
• Using web + Claude Code? Install the Chrome extension for combined tracking
• The extension shows total usage across all devices

Requirements

• Bash 4.0+
• jq (JSON processor)
• Waybar
• Claude Code (for fallback mode) or Chrome Extension (for accurate mode)

License

MIT

Contributing

Pull requests welcome! Please ensure:

• No credentials or hardcoded paths
• Shell script passes shellcheck
• Works on both Arch and Debian-based systems
• Follows existing code style

See Also

• Claude Usage Tracker Chrome Extension - For accurate session tracking
• Waybar - Status bar for Wayland
• Omarchy - Beautiful Arch Linux distribution

Credits

Created for use with Omarchy, but works with any Waybar setup.