Monitor Claude Code, OpenAI Codex CLI, GitHub Copilot, OpenCode Zen, and Z.ai usage directly in your Waybar status bar.

This tool displays your AI coding assistant usage limits in real-time by reading browser cookies or API tokens. No API key needed for Claude, Codex, or OpenCode Zen — they use the browser session you're already signed into.

• What This Monitors
• Requirements
• Installation
• Setup — Claude, Codex, Copilot, Zen, Z.ai
• Usage
• Formatting Configuration — see also docs/formatting.md
• Display States
• Troubleshooting
• Contributing — see also CLAUDE.md

• Claude Code: Claude's AI-powered code editor
  • 5-hour usage window
  • 7-day usage window
• OpenAI Codex CLI: OpenAI's command-line coding assistant
  • Primary (5-hour) window
  • Secondary (7-day) window
• GitHub Copilot: Monthly premium request quota (Pro/Pro+)
  • Requests consumed vs. included quota (default: 300)
  • Countdown to monthly reset (1st of month, 00:00 UTC)
• OpenCode Zen: Pay-as-you-go balance for curated coding models
  • Current account balance in USD
  • Color-coded warnings when balance is low
  • No API key needed - uses browser cookies
• Z.ai: Usage quota monitoring (GLM models)
  • 5-hour token usage window (percentage + reset timer)
  • Monthly tool quota (web search, web reader, ZRead)
  • Uses API token from config file

• Linux with Waybar running
• A signed-in browser session for whichever cookie-based providers you monitor — Claude.ai, ChatGPT, OpenCode. See Setup for the supported browser list.
• GitHub fine-grained PAT — required for Copilot (see Setup)
• Z.ai API token — required for Z.ai (see Setup)
• Python 3.11+ and uv (install uv)

yay -S waybar-ai-usage

# Install from GitHub
uv tool install git+https://github.com/NihilDigit/waybar-ai-usage

# Or install locally for development
git clone https://github.com/NihilDigit/waybar-ai-usage
cd waybar-ai-usage
uv build
uv tool install --force dist/waybar_ai_usage-*-py3-none-any.whl

git clone https://github.com/NihilDigit/waybar-ai-usage
cd waybar-ai-usage
uv sync

Each provider authenticates differently. Expand the ones you need.

claude-usage
codex-usage

mkdir -p ~/.config/waybar-ai-usage

# GitHub Personal Access Token
# Required permission: User permissions → Plan → Read-only
# Create at: https://github.com/settings/personal-access-tokens
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Monthly included premium request quota
# Copilot Pro = 300, Copilot Pro+ = 1500
COPILOT_QUOTA=300

copilot-usage          # Shows used/quota in terminal
copilot-usage --waybar # Shows Waybar JSON

zen-balance          # Shows balance in terminal
zen-balance --waybar # Shows Waybar JSON

mkdir -p ~/.config/waybar-ai-usage

# Z.ai API token from browser DevTools
ZAI_TOKEN=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...

zai-usage          # Shows usage in terminal
zai-usage --waybar # Shows Waybar JSON

After uv tool install:

# Setup helper (adds modules/styles with backups + confirmation)
waybar-ai-usage setup

# Cleanup helper (removes modules/styles with backups + confirmation)
waybar-ai-usage cleanup

# Restore latest backups (or pass specific backup paths)
waybar-ai-usage restore

# Preview changes without writing
waybar-ai-usage setup --dry-run
waybar-ai-usage cleanup --dry-run
waybar-ai-usage restore --dry-run

# Skip confirmation
waybar-ai-usage setup --yes
waybar-ai-usage cleanup --yes

# Claude usage
claude-usage

# ChatGPT usage
codex-usage

# GitHub Copilot usage
copilot-usage
copilot-usage --config ~/.config/waybar-ai-usage/copilot.conf  # custom config path

# OpenCode Zen balance
zen-balance

# Z.ai usage quota
zai-usage
zai-usage --config ~/.config/waybar-ai-usage/zai.conf  # custom config path

# Waybar JSON output
claude-usage --waybar
codex-usage --waybar
copilot-usage --waybar
zen-balance --waybar
zai-usage --waybar

# Use a specific browser (repeatable, tried in order)
claude-usage --browser chromium --browser brave
codex-usage --browser chromium

Note: setup/cleanup will rewrite your Waybar config JSONC and may change formatting or remove comments. Backups are created before any write.

In development mode:

uv run python claude.py
uv run python codex.py

uv tool install waybar-ai-usage

After installation, the commands claude-usage, codex-usage, copilot-usage, zen-balance, and zai-usage will be available in your PATH (along with waybar-ai-usage for setup/cleanup).

waybar-ai-usage setup

This will add the required Waybar modules and styles (with backup + confirmation). Copilot module is only added if ~/.config/waybar-ai-usage/copilot.conf exists (see Setup). If you want to force a specific browser order in Waybar, pass it here:

waybar-ai-usage setup --browser chromium --browser brave

pkill waybar && waybar &

Important Notes:

• Use full path ~/.local/bin/ to ensure modules work when Waybar is launched by systemd (auto-start on login). Without the full path, modules will only work when Waybar is manually started from a terminal.

The default output works without any configuration. To customize what each widget shows — variables, conditional blocks, custom layouts — see docs/formatting.md.

Color thresholds are defined in waybar-style-example.css and applied via Waybar CSS classes — edit the stylesheet to taste. The shipped defaults:

• Green — low usage (<50% for Claude/Codex/Copilot/Z.ai; healthy balance for Zen)
• Yellow — moderate usage (50–79%; low balance for Zen)
• Red — high usage (≥80%; near-empty balance for Zen)
• Critical (red, with bg tint) — fetch failed (auth or network error)

Special bar text states (Claude, Codex, Z.ai only):

• Ready — window hasn't been activated yet (0% used, full reset window remaining)
• Pause — quota exhausted (100% used). For Claude/Codex this means the long window (7-day / Secondary) is fully consumed

Make sure you're logged into Claude/ChatGPT in your chosen browser:

# Test Claude cookies
python -c "import browser_cookie3; print(list(browser_cookie3.chromium(domain_name='claude.ai')))"

# Test ChatGPT cookies
python -c "import browser_cookie3; print(list(browser_cookie3.chromium(domain_name='chatgpt.com')))"

1. Refresh the Claude/ChatGPT/OpenCode page in your browser
2. Check if your IP is blocked by Cloudflare
3. Update dependencies: uv sync --upgrade
4. Cookie-based providers (Claude, Codex, Zen) retry once on failure (10s timeout each); Copilot and Z.ai do not retry

If you have multiple browsers installed, the tool may pick one you're not actually signed into and then return errors like Missing 'lastActiveOrg' in cookies or Auth Err. Force a specific browser with --browser (repeatable, tried in order):

claude-usage --browser chromium --browser brave
codex-usage --browser helium

For Waybar, append --browser <name> to the exec line in your config, or pass it to waybar-ai-usage setup so it's baked in:

waybar-ai-usage setup --browser chromium

Default probe order if --browser is not given: chrome, chromium, brave, edge, firefox, helium.

Contributions welcome — especially new providers. See CLAUDE.md for the architecture overview, the provider contract, and the touch-points required when adding a provider.

MIT - See LICENSE file for details.

• Uses browser_cookie3 for cookie extraction
• Uses curl_cffi for making authenticated requests