ai-usagebar

Native Omarchy Quattro panel, Waybar widget, and tabbed TUI for AI plan usage across Claude, Codex/ChatGPT, GitHub Copilot, Z.AI (GLM), OpenRouter, DeepSeek, DeepInfra, Kimi, Nous Research, OpenCode Go, Command Code, Devin, Cline, Muse Code, Droid, Synthetic, DeepRelay, Mistral, and other supported AI coding services.

ai-usagebar began as a Rust port of claudebar and remains drop-in compatible. It keeps claudebar's Pango tooltip, Omarchy theme detection, and flock-protected OAuth refresh while adding more providers and a testable Rust codebase.

Features

• Per-provider Waybar modules use the same JSON shape and flags as claudebar.
• The native Omarchy Quattro plugin follows the shell theme and supports keyboard navigation, provider switching, live reset timers, and stale/error states.
• ai-usagebar-tui opens with a compact provider overview and refreshes every 60 seconds. Its navigation can use a sidebar, navbar, or no vendor box.
• An optional Claude Code context view reads recent local session usage without scanning entire histories.
• Native integrations are available for Omarchy, GNOME Shell, KDE Plasma 6, and a macOS/Windows system-tray popover (ai-usagebar-tray). An experimental GTK tray frontend for Linux Mint is in linux-mint/.
• One bar item can cycle through enabled providers. [ui] primary controls the initial provider in both the widget and TUI.
• Atomic caches and file locking prevent duplicate requests from multi-monitor Waybar setups.
• Quota-threshold desktop notifications are on by default: a window crossing 97% (configurable in [notifications] or macOS Preferences) raises one system alert per crossing on Linux and macOS. At 100% the limit is critical, and banked Codex/SuperGrok reset credits warn 48h before expiring. Set enabled = false under [notifications] to turn them off — see the configuration reference.
• Network failures keep the previous data visible; HTTP errors appear in the tooltip.
• A vendor that answers HTTP 429 is left alone for five minutes: the last good snapshot keeps showing marked as stale, or the entry reads "rate limited; next attempt in 4m" and no request is made until then (every vendor on the shared cache; Nous Research has its own path).
• --pretty, --watch N, and make smoke help with local testing and API response changes.

Reference guides

• Configuration
• Development guide
• TUI mouse support
• Windows build guide
• Ollama Cloud integration
• Claude accounts
• Format placeholders
• Provider endpoints and live tests
• KDE Plasma 6 plasmoid

Install

Nix

Run either application directly from GitHub:

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

Install both ai-usagebar and ai-usagebar-tui into your user profile:

nix profile install github:akitaonrails/ai-usagebar

For a flake-based NixOS or Home Manager configuration, add the input in your root flake.nix:

inputs.ai-usagebar.url = "github:akitaonrails/ai-usagebar";

Pass inputs to your NixOS modules with specialArgs:

nixpkgs.lib.nixosSystem {
  system = "x86_64-linux";
  specialArgs = { inherit inputs; };
  modules = [ ./configuration.nix ];
}

For standalone Home Manager, use extraSpecialArgs:

let
  system = "x86_64-linux";
in
home-manager.lib.homeManagerConfiguration {
  pkgs = nixpkgs.legacyPackages.${system};
  extraSpecialArgs = { inherit inputs; };
  modules = [ ./home.nix ];
}

If your configuration already passes inputs through these arguments, you do not need to add it again. Then consume the package in a NixOS module:

{ inputs, pkgs, ... }:
{
  environment.systemPackages = [
    inputs.ai-usagebar.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}

The equivalent Home Manager module is:

{ inputs, pkgs, ... }:
{
  home.packages = [
    inputs.ai-usagebar.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}

Alternatively, apply the overlay when you want the package available as pkgs.ai-usagebar:

{ inputs, pkgs, ... }:
{
  nixpkgs.overlays = [ inputs.ai-usagebar.overlays.default ];
  environment.systemPackages = [ pkgs.ai-usagebar ];
}

Omarchy Quattro

The native plugin is a display frontend and does not bundle the ai-usagebar executable. Both are needed, and they install through different managers — the binary is a system package, the plugin is per-user shell config under ~/.config/omarchy/plugins/ — so this is 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 found the plugin through plugins.omarchy.org, its Install button copies the omarchy plugin add line on its own. That installs the widget but not the binary it reads, and the bar will say ai-usagebar is not installed until you run the omarchy pkg aur add half too.

Quattro enables its own omarchy.agents status widget by default. Disable it if you want AI Usage to be the only agent status item in the bar:

omarchy plugin disable omarchy.agents

This is the beginning of the README. Read the rest at the original. Read the full README ↗