claudebar

Waybar widget that shows your Claude AI usage limits — session, weekly, and per-model — with colored progress bars and countdown timers.

Features

• Session (5h) and weekly (7d) usage with countdown timers
• Per-model tracking (Sonnet) when available
• Extra usage tracking (spending, limit, balance) when enabled
• Pacing indicators — ratio-based and point-based, with optional per-window coloring
• Tooltip elapsed markers — visual pacing reference in progress bars
• Colored progress bars in tooltip (Pango markup)
• Customizable bar text and tooltip via --format / --tooltip-format placeholders
• Granular CSS classes (low, mid, high, critical) for bar styling
• Response cache (60s TTL) — fast even on multi-monitor setups
• Auto-refreshes OAuth token (no manual re-auth needed)
• Pure Bash — no runtime dependencies beyond curl, jq, and GNU date
• Works with any Waybar setup (Hyprland, Sway, etc.)

Requirements

• Claude CLI — must be logged in (claude command)
• Claude Pro or Max subscription
• curl, jq, GNU date (standard on most Linux systems)
• Waybar
• A Nerd Font for tooltip icons
• (Optional) Font Awesome ≥ 7.2.0 OTF for the Claude brand icon

Installation

Arch Linux (AUR)

yay -S claudebar

From source

git clone https://github.com/mryll/claudebar.git
cd claudebar
make install PREFIX=~/.local

Or system-wide:

sudo make install

To uninstall:

make uninstall PREFIX=~/.local

Quick install

curl -fsSL https://raw.githubusercontent.com/mryll/claudebar/master/claudebar \
  -o ~/.local/bin/claudebar && chmod +x ~/.local/bin/claudebar

Quick start

Add the module to your ~/.config/waybar/config.jsonc:

"modules-right": ["custom/claudebar", ...],

"custom/claudebar": {
    "exec": "claudebar",
    "return-type": "json",
    "interval": 300,
    "signal": 13,
    "tooltip": true,
    "on-click": "xdg-open https://claude.ai/settings/usage"
}

[!WARNING]
The usage endpoint (/api/oauth/usage) is undocumented and has aggressive rate limits. Intervals below 300s will likely trigger HTTP 429 errors. Even at 300s, 429s may occur during Anthropic service disruptions. When this happens, the widget falls back to cached data and shows a ⏸ indicator. See claude-code#30930.

Configuration

Icon

Use --icon to prepend an icon to the widget text. The icon inherits the same color as the usage text.

Emoji:

"exec": "claudebar --icon '🤖'"
// => 🤖 42% · 1h 30m

Nerd Font glyph:

"exec": "claudebar --icon '󰚩'"
// => 󰚩 42% · 1h 30m

Claude brand icon (requires Font Awesome ≥ 7.2.0 OTF):

"exec": "claudebar --icon \"<span font='Font Awesome 7 Brands'>&#xe861;</span>\""

[!NOTE]
On Arch Linux, install the OTF package (sudo pacman -S otf-font-awesome). The WOFF2 variant (woff2-font-awesome) does not render in Waybar due to a Pango compatibility issue.

Colors

The bar text is colored by severity level out of the box (One Dark palette):

To override, pass --color-* flags in the exec field:

"custom/claudebar": {
    "exec": "claudebar --color-low '#50fa7b' --color-critical '#ff5555'",
    ...
}

Available flags: --color-low, --color-mid, --color-high, --color-critical.

CSS classes (low, mid, high, critical) are also emitted for additional styling via ~/.config/waybar/style.css.

Theming (Omarchy)

Tooltip and bar text colors are automatically read from the active Omarchy theme at ~/.config/omarchy/current/theme/colors.toml on every execution. On non-Omarchy systems, the One Dark palette is used as fallback.

The priority chain is: CLI flags (--color-*) > Omarchy theme > One Dark defaults.

Tokyo Night	Gruvbox	Catppuccin Latte

Format customization

Use --format to control the bar text:

# Default (session usage + countdown)
claudebar
# => 42% · 1h 30m

# Weekly usage
claudebar --format '{weekly_pct}% · {weekly_reset}'
# => 27% · 4d 1h

# Session + weekly
claudebar --format 'S:{session_pct}% W:{weekly_pct}%'
# => S:42% W:27%

# With pacing indicator
claudebar --format '{session_pct}% {session_pace} · {session_reset}'
# => 42% ↑ · 1h 30m

# Minimal
claudebar --format '{session_pct}%'
# => 42%

[!TIP]
For icons, use --icon (see Icon) instead of embedding them in --format. This lets you use Pango markup to select the font, which is necessary for brand icons like Font Awesome.

Use --tooltip-format for a custom plain-text tooltip (overrides the default rich tooltip):

claudebar --tooltip-format 'Session: {session_pct}% ({session_reset}) | Weekly: {weekly_pct}% ({weekly_reset})'

Example Waybar config with custom format:

"custom/claudebar": {
    "exec": "claudebar --format '{session_pct}% {session_pace}'",
    "return-type": "json",
    "interval": 300,
    "signal": 13,
    "tooltip": true,
    "on-click": "xdg-open https://claude.ai/settings/usage"
}

Available placeholders

[!NOTE]
Bar placeholders are colored by their own window's usage thresholds (low/mid/high/critical), independently of the surrounding bar text color, which reflects the worst window overall. A {session_bar} can render green while the surrounding text is red because weekly or sonnet hit the critical threshold.

Pacing indicators

Pacing compares your actual usage against where you "should" be if you spread your quota evenly across the window. It answers: "at this rate, will I run out before the window resets?"

• ↑ — ahead of pace (using faster than sustainable)
• → — on track
• ↓ — under pace (plenty of room left)

How it works: if 30% of the session time has elapsed, you "should" have used ~30% of your quota. The widget divides your actual usage by the expected usage and flags deviations beyond a tolerance band:

By default the tolerance is ±5% — deviations of 5% or less show as "on track" to avoid noise. You can tune it with --pace-tolerance:

# More sensitive (±2%) — flags smaller deviations
claudebar --pace-tolerance 2

# More relaxed (±10%) — only flags large deviations
claudebar --pace-tolerance 10

The {session_pace_pct} / {weekly_pace_pct} placeholders show the deviation (e.g. "12% ahead", "5% under", "on track").

Point-based pacing

In addition to ratio-based pacing, there's a point-based alternative that computes actual_usage - expected_usage. At 22% usage with 78% elapsed, the delta is -56 — intuitive and stable across the window.

Replace * with session, weekly, or sonnet.

Per-window pace coloring

Use --format-pace-color to color pace placeholders individually per window based on their point delta, instead of the global usage-based color:

claudebar --format-pace-color \
  --format '{session_pace_indicator}{session_pace_abs_delta}·{weekly_pace_indicator}{weekly_pace_abs_delta}'
# => ↑4·↓10  (↑4 in orange, ↓10 in green, · in neutral)

Without this flag, the entire bar text is colored by usage percentage — identical to the default behavior.

Tooltip elapsed markers

Use --tooltip-pace-pts to add an elapsed marker (█) to each tooltip progress bar, showing where even pacing would put you:

Without --tooltip-pace-pts:
  Session
    █████░░░░░░░░░░░░░░░  27% ↑

With --tooltip-pace-pts:
  Session
    █████░░░░░█░░░░░░░░░  27% ↑
                  ^ marker at 32% (even pace position)

The marker color adapts to the active theme. Without this flag, the tooltip is unchanged.

Spacing

Adjust padding (inside the widget) and margin (outside the widget) in ~/.config/waybar/style.css:

#custom-claudebar {
    padding: 0 8px;
    margin: 0 4px;
}

How it works

1. Reads OAuth credentials from ~/.claude/.credentials.json (created by Claude CLI)
2. Auto-refreshes the access token if it expires within 5 minutes
3. Calls api.anthropic.com/api/oauth/usage for live usage data (cached for 60s)
4. Outputs JSON with text, tooltip (Pango markup), and class for Waybar

The tooltip shows colored progress bars for each usage window (session, weekly, sonnet) with countdown timers, time elapsed, and pacing info. Colors change from green → yellow → orange → red as usage increases.

Cache

API responses are cached in ~/.cache/claudebar/usage.json for 60 seconds. This keeps the widget fast (~40ms from cache vs ~1s from API), which matters if you run multiple Waybar instances (e.g. multi-monitor).

Troubleshooting

Related

• codexbar — OpenAI Codex usage widget for Waybar
• logibar — Logitech battery widgets for Waybar
• meteobar — Weather widget for Waybar (Open-Meteo)
• ClaudeBar — Similar widget using TypeScript/Bun
• waybar-ai-usage — Claude + Codex monitor (Python, uses browser cookies)
• Omarchy — Beautiful, modern & opinionated Linux distribution
• Waybar — Status bar for Wayland compositors