TokenGauge

Monitor token usage from your Waybar. Powered by CodexBar. Built for Omarchy (GitHub) but works with any Waybar setup on Linux.

Waybar	TUI

Features

• Per-provider usage bars in Waybar
• TUI dashboard with colored progress bars and reset times
• Show daily or weekly usage (configurable)
• Smart caching to minimize API calls
• Click waybar module to open TUI

Supported Providers

Provider	Type	Config
Codex	OAuth	codex = true
Claude	OAuth	claude = true
Kimi K2	API	[providers.kimik2] with api_key
z.ai	API	[providers.zai] with api_key
Copilot	API	[providers.copilot] with api_key
MiniMax	API	[providers.minimax] with api_key
Kimi	API	[providers.kimi] with api_key

Installation

curl -fsSL https://raw.githubusercontent.com/oorestisime/TokenGauge/main/scripts/install.sh | bash
omarchy-restart-waybar

Click the waybar module to open the TUI dashboard.

Configuration

Edit ~/.config/tokengauge/config.toml:

Field	Description	Default
codexbar_bin	Path to CodexBar CLI	codexbar
refresh_secs	Cache refresh interval (seconds)	600
cache_file	Cache file location	/tmp/tokengauge-usage.json
providers.codex	Enable Codex (OAuth)	true
providers.claude	Enable Claude (OAuth)	true
providers.<name>.api_key	API key for API providers	—
waybar.window	Show daily or weekly usage	daily

Note: Waybar's interval controls how often the UI refreshes. Keep it shorter than refresh_secs so the UI updates from cache without extra API calls.

Usage

Waybar

The module displays per-provider usage bars. Hover for detailed tooltip with reset times.

TUI

Run tokengauge-tui or click the waybar module.

Key	Action
r	Refresh
q / Esc	Quit

Updates

# Update TokenGauge
curl -fsSL https://raw.githubusercontent.com/oorestisime/TokenGauge/main/scripts/update.sh | bash

# Update CodexBar CLI
curl -fsSL https://raw.githubusercontent.com/oorestisime/TokenGauge/main/scripts/update-codexbar.sh | bash

Without Omarchy

The install script detects Omarchy automatically. Without it, you'll need to configure the TUI click handler manually.

Edit ~/.config/waybar/config.jsonc and add on-click to the tokengauge module:

"custom/tokengauge": {
  "exec": "tokengauge-waybar",
  "return-type": "json",
  "interval": 60,
  "on-click": "ghostty -e tokengauge-tui"
}

Other terminals: alacritty -e tokengauge-tui, kitty -e tokengauge-tui, foot tokengauge-tui

Manual Installation

1. Download the latest release from GitHub Releases

2. Extract and install:

   tar -xzf tokengauge-<version>-linux-<arch>.tar.gz
   install -m 0755 tokengauge-waybar ~/.local/bin/
   install -m 0755 tokengauge-tui ~/.local/bin/

3. Create config:

   mkdir -p ~/.config/tokengauge
   cat > ~/.config/tokengauge/config.toml << 'EOF'
   codexbar_bin = "codexbar"
   refresh_secs = 600
   cache_file = "/tmp/tokengauge-usage.json"
   
   [providers]
   codex = true
   claude = true
   
   # API providers (uncomment and add your API key)
   # [providers.kimik2]
   # api_key = "your-api-key"
   
   [waybar]
   window = "daily"
   EOF

4. Add to waybar config (~/.config/waybar/config.jsonc):

   "modules-right": ["custom/tokengauge", ...],
   "custom/tokengauge": {
     "exec": "tokengauge-waybar",
     "return-type": "json",
     "interval": 60,
     "on-click": "ghostty -e tokengauge-tui"
   }

5. Install CodexBar CLI if not already installed

6. Restart Waybar