ai-usagebar: A Rust Waybar Widget and TUI for Multi-Provider AI Plan Usage

What ai-usagebar solves, and for whom

If you pay for more than one AI coding plan, the quota question becomes annoying. Claude has a five-hour window and a weekly one. Codex has its own. OpenRouter is credits, not a window. GLM, DeepSeek, Kimi, Copilot and Nous Research each answer a different endpoint with a different payload. Checking them means opening several dashboards, and the answer is only useful while you are already looking at your desktop.

ai-usagebar puts that answer in the bar you already have. It is a Rust project that renders per-provider Waybar modules, a native Omarchy Quattro panel, and a tabbed TUI called ai-usagebar-tui. The README describes it as a port of claudebar that stays drop-in compatible: same JSON shape, same flags, same Pango tooltip, same Omarchy theme detection, same flock-protected OAuth refresh. The audience is narrow and specific. You run Waybar on Sway or a similar compositor, or you run Omarchy, or you are willing to open a TUI. If you use a stock GNOME or KDE desktop and never touch a terminal widget, the value proposition is thinner, even though the repository ships a GNOME extension and a KDE Plasma 6 plasmoid.

The project also covers a case the source tools do not: one bar item that cycles through enabled providers, controlled by [ui] primary for the initial provider in both the widget and the TUI. That is a different design from running six separate modules and reading six numbers.

How the polling, caching and rate-limit handling actually work

The architecture is a Rust binary that queries provider endpoints over reqwest with rustls, parses the responses with serde, and writes snapshots to a cache that the frontends read. The README states that the caches are atomic and file-locked, which prevents duplicate requests when several Waybar instances run, as happens on a multi-monitor setup. That detail matters more than it sounds: without locking, three monitors means three times the request volume against endpoints that rate limit.

Failure handling is where the design shows a point of view. Network failures keep the previous data visible rather than blanking the widget, and HTTP errors surface in the tooltip instead of the bar text. A vendor that answers HTTP 429 is left alone for five minutes. During that window the last good snapshot keeps showing, or the entry reads something like "rate limited; next attempt in 4m", and no request is made until the timer expires. The README notes this applies to every vendor on the shared cache, with Nous Research on its own path. That is a deliberate choice to trade freshness for not making the rate limit worse.

The TUI opens with a compact provider overview and refreshes every 60 seconds. Navigation can use a sidebar, a navbar, or no vendor box. There is also an optional Claude Code context view that reads recent local session usage without scanning entire histories, which is a scoped read rather than a full index. The repository includes a docs/format-placeholders.md and docs/vendor-endpoints.md, so the endpoint list and the placeholder vocabulary are documented rather than buried in source.

Installing ai-usagebar and getting a first reading

There are three install paths in the README, and they are not interchangeable. On Nix, you can run either application directly from GitHub without installing anything:

nix run github:akitaonrails/ai-usagebar
nix run github:akitaonrails/ai-usagebar#tui

The first command starts the widget binary, the second the TUI. To keep them, install both into your user profile:

nix profile install github:akitaonrails/ai-usagebar

On Arch, the README offers two AUR packages. The -bin variant downloads the prebuilt x86_64 ELF that CI built, and the source variant compiles locally. Both install identical binaries to /usr/bin/, and pacman handles switching between them through conflicts and provides:

yay -S ai-usagebar-bin    # prebuilt binary from GitHub Releases
yay -S ai-usagebar        # compiles from source

Elsewhere on Linux or macOS, the crate is on crates.io. The README gives cargo install for a source build and cargo binstall for a prebuilt one, the latter requiring cargo-binstall. Cargo.toml sets rust-version to 1.88 and edition 2024, so an older toolchain will refuse the build.

For the Omarchy Quattro panel there is a trap worth naming. The plugin is a display frontend and does not bundle the executable. Both are needed, and they install through different managers, which is why the README gives one paste rather than one command:

omarchy pkg aur add ai-usagebar-bin &&
  omarchy plugin add https://github.com/akitaonrails/ai-usagebar.git --enable

If you install the plugin from plugins.omarchy.org, the Install button copies only the plugin half, and the bar will read "ai-usagebar is not installed" until you run the package half too. Once it is running, left-click opens the usage panel, the gear or the s key opens the QML settings page, and right-click opens ai-usagebar-tui in a terminal. That last mapping is intentional and is not the settings shortcut.

Where ai-usagebar is the wrong tool

The project assumes a desktop shell it can draw into. Waybar, Omarchy, GNOME Shell, KDE Plasma 6, the macOS menu bar and a Windows tray popover are all covered, but each is a separate integration, and the README does not claim they are feature-identical. The Quattro panel gets keyboard navigation, provider switching, live reset timers and stale states. Whether the Windows tray popover exposes the same settings surface is not stated in the README, and docs/windows-build.md is where that would live.

The second limitation is the one that bites in practice. The tool can only show what a provider endpoint returns. If a vendor changes its response, the widget shows an error in the tooltip rather than a number. The README points at --pretty, --watch N and make smoke as the tools for spotting API response changes, which tells you the maintainers expect this to happen. A quota widget that silently shows stale figures is worse than one that shows an error, and this project chose the error.

Third, the Claude Code context view reads recent local session usage. It is scoped by design and explicitly does not scan entire histories. If you want a full accounting of every token you have ever spent through Claude Code, this is not that tool. It answers "what is my plan doing right now", not "what did I do last quarter".

ai-usagebar against claudebar and the CodexBar family

The README is direct that ai-usagebar began as a Rust port of claudebar and remains drop-in compatible. That is the honest framing of the alternative: if you already run claudebar and it covers Claude only, staying on it costs you nothing, and ai-usagebar is designed so your existing Waybar config keeps working. The difference is provider count and the language the thing is written in. claudebar is the original; ai-usagebar adds providers and a testable Rust codebase, and keeps claudebar's Pango tooltip, Omarchy theme detection and flock-protected OAuth refresh.

The other comparison people search for is the CodexBar family, which the related searches show as a common point of reference. CodexBar's internals are not described in the README, so the only defensible statement is directional: ai-usagebar is a Waybar and Omarchy-first tool with a TUI, and its provider list is the one printed in its own README, which includes Claude, Codex/ChatGPT, GitHub Copilot, Z.AI (GLM), OpenRouter, DeepSeek, Kimi, Nous Research, OpenCode Go and Command Code. If your setup is a Linux bar, that list is the relevant one. If you want a macOS menu bar app as the primary surface, the repository does ship a macos/ directory, but the README treats it as one integration among several rather than the main one.

Licence, packaging and the cost of upgrading

ai-usagebar is MIT licensed, and the Makefile installs LICENSE to share/licenses/ai-usagebar/LICENSE alongside the binaries. MIT is permissive, so redistributing the binary in a package is straightforward, but the usual disclaimer applies: this is a description of what the repository does, not legal advice.

The packaging layout is worth understanding before you file a bug. The Makefile has separate install and install-plasmoid targets, and the comment states that install-plasmoid is deliberately not part of install because dropping a plasmoid into /usr/share/plasma on a machine with no Plasma is rude. KDE users run both. The Makefile also notes that KPackage only scans XDG_DATA_DIRS, which is why PLASMOID_DIR is built from an absolute path. If you install the plasmoid and it does not appear, that path resolution is the first thing to check.

Upgrade cost is low but not zero. The binary is a single Rust executable, so upgrading means replacing it; the AUR packages swap through conflicts and provides. The real upgrade risk is configuration drift. The README lists a config.example.toml, and docs/configuration.md is the reference. The TUI's navigation mode, the [ui] primary setting and the Quattro top-bar options (Show usage value in the top bar, Show provider name in the top bar, Top bar usage window) all live in configuration, and a release that adds a provider can add keys. The repository has a CHANGELOG.md, which is where those changes would be recorded.

Editorial conclusion

Adopt ai-usagebar if you already run Waybar or Omarchy and want one bar item cycling several providers, with atomic caches and a five-minute backoff on HTTP 429. Do not adopt it if you want a cross-platform GUI or a hosted dashboard; the native integrations are per-platform and the binary must be installed separately from the Omarchy plugin. Before trusting the numbers, run ai-usagebar --pretty against one provider and confirm the JSON shape matches what your Waybar config expects.

Frequently asked questions

Official sources

1. akitaonrails/ai-usagebar on GitHub
2. Issues
3. License: MIT
4. README
5. Releases