claudebar

claudebar shows how much of your Claude AI plan you have used, in Waybar and in the Omarchy shell. It shows the session limit, the weekly limit and the per-model limits. Each one has a progress bar, a color for the level of use, and the time until it resets.

The same core drives both frontends, so a number reads the same on either one:

Contents

• Features
• Requirements
• Installation
• Quick start
• Omarchy shell plugin
• Configuration
• Structured JSON output
• How it works
• Troubleshooting
• Related

Features

• Session (5h) and weekly (7d) limits, each with a countdown to the reset.
• Per-model limits, such as a weekly limit for one model, when the API reports them.
• Extra usage: the money spent this month, the prepaid balance that is left, and the monthly limit.
• Pace indicators that compare your use with the time that has passed.
• A color gauge in the tooltip: green at 0%, amber in the middle, red at the top.
• Custom bar text and tooltip text through --format and --tooltip-format.
• CSS classes (low, mid, high, critical) for your own bar style.
• A monochrome mode for a bar without color, with support for NO_COLOR.
• A native plugin for the Omarchy shell, with a usage panel that opens on a click.
• Structured JSON output (--json) for other frontends.
• Automatic refresh of the OAuth token. You do not log in again.
• Pure Bash. The only external tools are curl, jq, GNU date, and the standard text tools.

Requirements

• Claude CLI. You must be logged in with the claude command.
• A Claude Pro or Max subscription.
• curl, jq and GNU date. These are standard on most Linux systems.
• Waybar.
• A Nerd Font for the tooltip icons, and for the rules that line up its columns. Refer to Tooltip font.
• Optional: Font Awesome 7.2.0 or later, in OTF format, for the Claude brand icon.

Installation

Omarchy

On Omarchy, the complete installation is two commands:

yay -S claudebar
omarchy plugin add https://github.com/mryll/claudebar.git --enable

The first command installs the CLI. The second command installs the bar widget and enables it. Refer to Omarchy shell plugin for the panel and its settings.

Arch Linux (AUR)

yay -S claudebar

From source

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

To install for all users:

sudo make install

To remove the widget:

make uninstall PREFIX=~/.local

One command

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 file:

"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"
}

Run claudebar --help for the full reference: the usage line, every flag, and the format placeholders.

A compact line in your bar. Move the pointer onto it to see all the limits:

[!WARNING] The OAuth usage endpoint and the prepaid-credit endpoint are not documented. The usage endpoint has strict rate limits. An interval of less than 300 seconds will usually cause HTTP 429 errors. Errors are also possible at 300 seconds if the Anthropic service has a problem. If this occurs, the widget shows the data from the cache with a  pause sign. If the balance is not available, the widget shows it as unknown. It does not show the monthly limit in its place. Refer to claude-code#30930.

Omarchy shell plugin

claudebar also has a native plugin for the Quickshell bar of the Omarchy shell. The plugin is in the omarchy/ directory of this repository. The bar shows the Claude glyph and a short usage percentage. A click opens a panel with one section for each limit. The footer of the panel ends with a refresh control (󰑐), next to the time of the last update. The control stays disabled while a fetch runs.

Each section has an animated progress bar, the percentage, the countdown to the reset, and the pace indicator. Below the sections, the panel shows the extra usage and the state of the cache.

Each meter paints a color gauge along its full length and fills it up to the current value. The meter reads like a thermometer against a scale. It does not change its color as one block. The CLI resolves the gauge and sends it in the palette field of its JSON output: the colors and also the percentages where they turn. The panel reads those stops and calculates the colors between them. Thus one change in the core moves the tooltip and the panel together. Each number takes the color of the gauge at its own value, so the number and its meter always agree.

A small dot appears next to the percentage when a limit that is not on the bar becomes critical (90% or more). Thus a per-model limit that is almost full still gets your attention while the bar shows a comfortable session number. Move the pointer onto the widget and a tooltip gives the name of that limit, for example Fable · Weekly: 100%. When there is no dot, there is no tooltip, and the panel stays the full view of the data.

Mouse and keyboard controls:

The plugin also answers the shell's IPC, so a keybind or a script can drive it without the mouse:

qs ipc call mryll.claudebar toggle    # open or close the panel
qs ipc call mryll.claudebar refresh   # fetch now, without opening anything

Install the plugin

From the marketplace, or from this repository directly:

omarchy plugin add https://github.com/mryll/claudebar.git --enable

That clones the repository into ~/.config/omarchy/plugins/mryll.claudebar and validates the manifest before it is enabled. To remove it later: omarchy plugin remove mryll.claudebar.

The plugin runs the claudebar CLI from your PATH, so install that too — from the AUR (yay -S claudebar) or with make install PREFIX=~/.local.

For development, link the working copy instead of cloning a second one:

make install-omarchy

This command makes a symbolic link from the repository to ~/.config/omarchy/plugins/mryll.claudebar. The manifest is in the root of the repository and points to omarchy/.

Then add the widget to a bar section in ~/.config/omarchy/shell.json:

{
  "bar": {
    "layout": {
      "right": [
        { "id": "mryll.claudebar" }
      ]
    }
  }
}

[!IMPORTANT] The shell does not detect file changes through a symbolic link. After you edit a plugin file, run omarchy restart shell. A rescanPlugins command finds new plugins, but it does not compile the QML again.

To remove the plugin, run make uninstall-omarchy. This removes only the symbolic link.

Plugin settings

Change these settings in the settings window of the shell, or write them in the shell.json entry:

[!NOTE] The Waybar mode continues to be the default mode, and it has full support. The Omarchy plugin is one more frontend on top of the same script.

Configuration

Icon

Use --icon to put an icon before the widget text. The icon takes the same color as the usage text.

An emoji:

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

A Nerd Font glyph:

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

The Claude brand icon. This needs Font Awesome 7.2.0 or later in OTF format:

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

[!NOTE] On Arch Linux, install the OTF package with sudo pacman -S otf-font-awesome. The WOFF2 package (woff2-font-awesome) does not work in Waybar because of a Pango problem.

Colors

The color of the bar text follows the level of use. These are the default colors, from the One Dark palette:

To use other colors, add the --color-* flags to the exec field:

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

The four flags are --color-low, --color-mid, --color-high and --color-critical. Each one accepts a hex color (#rgb, #rgba, #rrggbb or #rrggbbaa) or a plain color name such as red. Other values cause an error message in the widget.

In the tooltip these four colors are the anchors of a gauge, not four steps. Low sits at 0%, mid at 50%, high at 75%, and critical from 90% up. The script calculates all the colors between the anchors. Each progress bar paints that gauge along its own length: cell number k takes the color of the percentage at its position. Thus a bar goes from green to red from left to right, and the length of the fill shows your position on the scale. Each number next to a bar takes the color of the gauge at its own value.

The class field (low, mid, high, critical) stays at the four discrete steps above. Use it in ~/.config/waybar/style.css for your own style.

Theming (Omarchy, pywal)

The script resolves the colors of the bar and the tooltip at each execution, in this order:

Each source fills only the colors that the sources above it did not set. Thus one --color-critical flag leaves the other three colors to your theme. The script reads the pywal palette only when there is no Omarchy theme. pywal never replaces Omarchy.

[!NOTE] Change for users of an earlier version. The detection of the Omarchy theme did not work. The script read the path of Omarchy 3, and it also needed the old color1 key. The result was that the tooltip used the built-in palette without a message. The colors now follow your real theme. The tooltip also has the color gauge that this page describes.

pywal support makes the widget agree with a system that does not use Omarchy. The path above is the usual one. The first pywal is now an archive, but the pywal16 fork writes the same file, and wallust has a target that is compatible with pywal. Thus the three tools work with no configuration.

The script maps special.foreground and special.background to the text and the surfaces. It maps colors.color1 to red, color2 to green, color3 to yellow, and color4 (or special.cursor) to the accent. pywal has no slot for orange, so the script calculates orange as the middle point between yellow and red. This keeps four different steps in the gauge. A key that is not there keeps its built-in default. A value that is not a hex color is ignored. A colors.json file that is absent, unreadable or damaged causes no error: the script uses the One Dark colors.

The Omarchy plugin follows the same theme. These are three Omarchy themes in the panel:

Monochrome mode

Do you prefer a bar without color? --no-color removes the color from all surfaces, or from one surface only:

"custom/claudebar": {
    "exec": "claudebar --no-color",         // plain bar text and plain tooltip
    // "exec": "claudebar --no-color=bar",     // plain bar, colored tooltip
    // "exec": "claudebar --no-color=tooltip", // colored bar, plain tooltip
    ...
}

Plain means no color markup. Nothing else changes. The progress bars, the markers, the icons, the box lines, the bold text and all the numbers stay in their positions. The flag also removes color markup that you wrote yourself in a --format or --tooltip-format value.

The widget obeys the NO_COLOR environment variable. Set it to any value that is not empty and the widget operates as with --no-color=all. A flag is a more specific instruction than the variable, so NO_COLOR=1 claudebar --no-color=tooltip keeps the color in the bar text.

[!TIP] Monochrome plus CSS: make your own style. The class field (low, mid, high, critical) does not change in monochrome mode. Thus you can remove the built-in colors and control the bar from your own stylesheet:

#custom-claudebar.high     { color: #d79921; }
#custom-claudebar.critical { color: #cc241d; font-weight: bold; }

The Omarchy plugin has the same four modes in its Colors setting (full, none, bar-only, panel-only). Refer to the settings table.

Bar text and tooltip text

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 (refer to Icon). Do not put icons in --format. The --icon flag lets you select the font with Pango markup, which is necessary for brand icons such as Font Awesome.

Use --tooltip-format for a tooltip of plain text. It replaces the default tooltip:

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

A Waybar config with a 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"
}

Placeholders

[!NOTE] ¹ If the API reports more than one model limit, the tooltip shows one section for each model. The {model_*} placeholders refer to the first model.

[!NOTE] Each bar placeholder takes its color from its own limit, not from the text around it. The text around it shows the highest of all the limits. Thus {session_bar} can be green while the text is red, because the weekly, the sonnet or a model limit is critical.

Remaining mode

Use --remaining to show what is left, as a battery does, in the default bar text and in the tooltip:

# Default (usage framing)
claudebar
# => 42% · 1h 30m

# Remaining framing
claudebar --remaining
# => 58% · 1h 30m

The tooltip header gets a · Remaining suffix, and the default bar text becomes {session_remaining_pct}% · {session_reset}. The flag changes only the default format and the tooltip header. Your own --format and --tooltip-format values do not change.

The {*_remaining_pct} and {*_remaining_bar} placeholders are available with or without this flag.

Pace indicators

The pace compares your use with the time that has passed in the limit period. It answers this question: at this rate, will the quota end before the reset?

• ↑ — ahead of the pace. You use the quota faster than the time.
• → — on the pace.
• ↓ — behind the pace. Much of the quota is left.

If 30% of the session time has passed, an even use is 30% of the quota. The script divides your real use by that expected use, and shows a difference that is larger than a tolerance band:

The default band is ±5%. A difference of 5% or less shows as "on pace". Change the band 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} and {weekly_pace_pct} placeholders show the difference, for example "12% ahead", "5% under" or "on pace".

Pace in points

There is a second calculation in points: real use minus expected use. At 22% use with 78% of the time passed, the difference is -56 points. This number is easy to read and it is stable during the period.

Replace * with session, weekly, sonnet or model.

One color for each pace

Use --format-pace-color to give each pace placeholder its own color from its point difference. Without this flag, the usage color applies to all the bar text.

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)

Markers in the tooltip

Use --tooltip-pace-pts to add a marker (┃) to each progress bar in the tooltip. The marker shows where an even pace would have you:

Without --tooltip-pace-pts:
  ██████░░░░░░░░░░░░░░     34%

With --tooltip-pace-pts:
  ██████░░░░░┃░░░░░░░░     34%
             ^ even-pace position

The color of the marker follows the active theme. Without this flag, the tooltip does not change.

Tooltip font

The tooltip is pinned to a monospace font. That is not decoration: its rules are box-drawing characters, and in a proportional font one of those is nearly twice as wide as a letter. The tooltip then sizes itself to the rules, and a dead margin opens to the right of the text. Waybar draws the tooltip in a GTK window that ignores font-family from your CSS, so the markup is the only place this can be said.

The default is a list of families, tried in order:

JetBrainsMono Nerd Font, JetBrainsMono Nerd Font Mono, monospace

Pango falls through to the next name when one is not installed. Both families are fully monospaced — every glyph, icons included, advances 0.6 em — so the rules align the same with either. The difference is the drawn size of the icons: the …Mono family shrinks them to fit the cell, about 40% smaller. The non-Mono family draws them at full size, and for that reason it comes first. The Arch package ttf-jetbrains-mono-nerd ships both families; ttf-jetbrains-mono-nerd-basic — the one Omarchy installs — ships only the non-Mono one.

To use a different font, name any monospace family (or your own list):

claudebar --tooltip-font "FiraCode Nerd Font Mono"

[!NOTE] --frame and --frame-font are deprecated. --frame drew the tooltip as a bordered card. It is still accepted, so an existing Waybar config keeps working, but it now does nothing; --frame-font is an alias for --tooltip-font.

The box was a second way of drawing the same content — more code, more documentation, more screenshots — and it only lined up when the pinned font was a complete Mono Nerd Font. Pinning the font on the one remaining tooltip gives the alignment without the box.

Space around the widget

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

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

Structured JSON output

claudebar --json prints one JSON object with the data and no markup. Use this output for your own bar, your own script, or a status page. The command always exits with 0, and it always prints valid JSON, also after an error.

claudebar --json | jq
claudebar --json --refresh   # force a fresh API fetch

Each entry in windows has: id, label, group (the meter it belongs to, for a per-model limit), used_pct, remaining_pct, reset_at, reset_at_unix, window_seconds, elapsed_pct, state, and a pace object.

The pace object has delta_points (your use minus the elapsed time, in percentage points), state (under, on_pace, ahead, or hot), icon and indicator (the arrow), ratio_label and points_label (the text that the tooltip prints).

palette.stops is the gauge itself: the colors, and the percentage where each color is. The value is a list of {pct, color}, from 0 to 100. A frontend reads the list and mixes the colors between the stops, so it does not need to know the limits. If you move a limit in the script, the bar, the tooltip, the state field, and the panel change together.

[!IMPORTANT] schema_version went from 1 to 2, and version 2 breaks version 1. The reason: claudebar and codexbar now print the same document, so one script reads both. What changed: the session, weekly, sonnet and models keys became the one windows list, where label is the window and group is the meter it belongs to; resets_at became reset_at; pace.delta_pts and pace.pts_label became pace.delta_points and pace.points_label; the cache object became the stale, stale_reason, updated_at and data_age_seconds fields; overall.max_pct and overall.state became max_pct and state; an API error behind old data moved from error to last_error, and error now means only a hard failure; loading, error and windows are always present; palette.stops has a fifth stop at 100.

[!NOTE] The script always exits with code 0, in JSON mode also. Waybar hides a module that exits with an error, so a problem is data in the error field, not an exit code.

In extra_usage, used_credit_cents is the money spent this month, available_credit_cents is the exact prepaid balance, and monthly_limit_cents is only a safety limit. funded_credit_cents is the spend plus the balance. Thus used_pct and the meter measure the real money, not the monthly limit. The fields that come from the balance are null when the separate ledger endpoint is not available. One exception: the explicit out_of_credits state of Claude means a balance of zero.

How it works

1. The script reads the OAuth credentials from ~/.claude/.credentials.json. The Claude CLI writes that file.
2. It refreshes the access token if the token expires in less than 5 minutes.
3. It calls api.anthropic.com/api/oauth/usage for the usage data.
4. It writes JSON with the text, tooltip and class fields for Waybar.

The tooltip shows a progress bar for each limit, with the countdown, the time that has passed and the pace. Each bar paints the green-to-red gauge along its length and fills it up to the current value.

Cache

The script keeps the API response in ~/.cache/claudebar/usage.json for 60 seconds. The cache makes the widget fast: about 40 ms from the cache, against about 1 second from the API. This is important if you run more than one Waybar instance, for example with more than one monitor. A lock makes the instances share one API call.

Troubleshooting

The tooltip does not use my Omarchy theme. Examine $XDG_STATE_HOME/omarchy/current/theme/colors.toml. If your shell does not set XDG_STATE_HOME, the file is at ~/.local/state/omarchy/current/theme/colors.toml. A claudebar version from before the fix above reads only the older path.

The panel does not show my changes to a plugin file. Run omarchy restart shell. The shell does not compile the QML again after a rescanPlugins command.

The bar text has no color, and I did not ask for that. Examine the NO_COLOR environment variable. Any value that is not empty operates as --no-color=all.

Related

• codexbar — OpenAI Codex subscription usage
• logibar — the battery of Logitech devices
• meteobar — the weather, from Open-Meteo
• printbar — any printer: supplies, trays and queue
• tickerbar — prices of crypto, stocks, indices, commodities and forex
• ClaudeBar — a similar widget in TypeScript and Bun
• waybar-ai-usage — a Claude and Codex monitor in Python, which uses browser cookies
• Omarchy — the Linux setup for these widgets
• Waybar — the status bar for Wayland