Claude + Codex Usage Waybar Module

A custom Waybar module that displays your Claude and OpenAI Codex subscription usage, showing percentage differences that compare your usage rate to your position in each time window.

Features

• Displays Claude weekly (7-day) and session (5-hour) limits alongside Codex rate limits
• Shows percentage differences indicating if you're using more (+) or less (-) than the expected rate
• Each provider is fetched independently: if one is unavailable, the other still displays
• Simple text-only display format
• No external dependencies - uses only Python built-in libraries

Requirements

• Python 3.8+
• Waybar
• For the Claude segment: Claude Code CLI, authenticated
• For the Codex segment: Codex CLI, authenticated

Neither CLI is required for the other's segment to work. If only one is installed, the module simply shows that one.

Installation

1. Clone or download this repository

2. Make the script executable:

   chmod +x claude_usage_waybar.py
   

3. Ensure the CLIs you want tracked are installed and authenticated:

   claude --version
   codex --version
   

Usage

Testing the Script

Run the script directly to see the output:

./claude_usage_waybar.py

Expected output:

{"text": "C W+5.2 S-3.1 | X W-41.6", "tooltip": "Claude\n  Weekly:  18.5% used (13.3% elapsed) = +5.2%, resets 2026-08-23 23:42\n  Session: 25.0% used (28.1% elapsed) = -3.1%, resets 2026-08-18 01:38\n\nCodex (plus)\n  Weekly:  19.0% used (60.6% elapsed) = -41.6%, resets 2026-08-20 16:14\n  Credits: 0", "class": "claude-usage", "percentage": 19}

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

C W+5.2 S-3.1 | X W-41.6

• C: Claude
• X: Codex
• W: Weekly usage difference
• S: Session (shorter window) usage difference
• +: Using more than expected at this point in the time window
• -: Using less than expected

Each provider contributes only the windows its API actually reports. Claude currently reports both a weekly and a 5-hour window. Codex reports a weekly window on most plans, and a second shorter window appears automatically if your plan gains one.

Interpretation

If the display shows C W+5.2:

• You've used 18.5% of your Claude 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 X W-41.6:

• You've used 19.0% of your Codex weekly quota
• You're 60.6% through the window
• Difference: 19.0% - 60.6% = -41.6%
• This means you're well under the average rate

Tooltip

Hover over the module to see detailed information:

• Actual usage percentages and time elapsed percentages per window
• Reset times for each window
• Your Codex plan type and credit balance
• The specific reason a provider is missing, when one is

Troubleshooting

A provider that cannot be read is dropped from the text, and the tooltip explains why. When both providers fail, the module shows usage unavailable and takes the claude-usage-error class. Run the script directly to see the full tooltip text.

"credentials not found or invalid"

The script cannot find that provider's credentials. Claude credentials are read from ~/.claude/.credentials.json and Codex credentials from ~/.codex/auth.json. Re-authenticate the CLI in question.

"token expired"

The stored OAuth token has expired, so no request is made. Start the relevant CLI to refresh it, or log in again:

claude auth login
codex login

"auth failed"

The token was rejected. Re-authenticate as above.

"HTTP 404" on the Codex segment

The Codex endpoint is an undocumented internal ChatGPT backend route and can change between Codex releases. See Technical Details.

"network error" or "timeout"

Check your internet connection and the relevant provider's status.

How It Works

1. Read credentials: the Claude OAuth token from ~/.claude/.credentials.json, the Codex token from ~/.codex/auth.json
2. Check expiry before requesting: Claude stores an explicit expiresAt; Codex expiry is read from the exp claim of the access token JWT. An expired token means no request is made.
3. Fetch usage: authenticated GET to each provider's usage endpoint
4. Calculate differences: compare usage percentage to time elapsed percentage for every reported window
5. Format output: return JSON in Waybar-compatible format

Technical Details

• No caching: fetches fresh data on every execution
• Request timeout: 10 seconds per provider
• Recommended interval: 120-300 seconds
• Built-in libraries only: urllib, json, base64, datetime, pathlib
• percentage field: reports the higher of the two weekly usages, so it reflects whichever quota is closer to exhaustion

Endpoints

Provider	Endpoint
Claude	https://api.anthropic.com/api/oauth/usage
Codex	https://chatgpt.com/backend-api/wham/usage

The Codex endpoint is not a documented public API. It is the route the Codex CLI itself uses, and it may change or disappear in a future Codex release. When that happens the Codex segment disappears from the bar and the tooltip reports the HTTP status. The JWT exp claim is decoded without signature verification, which is appropriate here because the token is only being checked for staleness before use, not trusted for authorization.

References

• Waybar Custom Module Documentation
• Claude Code CLI Documentation
• Codex CLI Documentation