Usage Monitor

Windows / Linux / macOS tray app for live quota of Claude, Codex, Grok, OMP, and 9Router. No API key entry: it reads the CLI login you already have.

What it tracks

Source	When it appears	Credentials
Claude	Claude CLI logged in	~/.claude/.credentials.json
Codex	Codex CLI logged in	~/.codex/auth.json
Grok	Grok CLI logged in	~/.grok/auth.json
OMP	omp on PATH (or %LOCALAPPDATA%\omp\omp.exe)	omp usage --json — one source per logged-in OMP provider
9Router	Local 9Router running	http://localhost:20128 (quota-capable providers only)
Custom	HTTP source in Settings (test URL, pick fields)	usage-monitor-settings.json

A provider with no account stays off the list. Native CLI, OMP, and 9Router of the same provider are separate entries.

Features

• Live tray icon — session + weekly bars, or stacked percentages via icon_style. Theme-aware.
• Detail popup — left-click (Windows and macOS). Account, reset countdown, extra usage, quota bars. Pin it. Compact view via compact_hide.
• Smart alerts — per-quota thresholds, time-aware mode, reset toasts.
• Event commands — shell command on reset, threshold, startup, or tray quick action.
• Adaptive polling — faster while usage climbs, pauses when idle/locked, aligns to the next reset.
• Start at login — tray menu, Windows, Linux, and macOS.
• 13 languages — auto-detected, override with language.

Security

Credentials stay on disk where the CLI put them. Used only as HTTP Authorization headers. Never logged.

Network: Anthropic (api.anthropic.com), OpenAI Codex (chatgpt.com), xAI Grok (cli-chat-proxy.grok.com, auth.x.ai, grok.com), optional local 9Router (localhost:20128) plus any custom URL you add. OMP stays local: the app runs omp usage --json and does not read OMP credential files.

No analytics, tracking, or telemetry. See PRIVACY.md.

Requirements

• Windows 10/11 (64-bit), Linux (freedesktop tray), or macOS.
• At least one logged-in CLI (Claude, Codex, Grok, or OMP) or a running 9Router.

Missing token: tray shows !. Log in to that CLI; the next poll picks it up. Claude 401 runs claude update. Codex/Grok refresh their own OAuth tokens.

Install

Download the latest release — pick one file:

You have	Download
Windows	x64-setup.exe (MSI is optional)
macOS Apple Silicon	aarch64.dmg
macOS Intel	x64.dmg
Debian / Ubuntu	.deb (amd64 or arm64)
Fedora / RHEL	.rpm (x86_64 or aarch64)
Any Linux	.AppImage
Arch	packaging/arch/PKGBUILD

Skip .sig, .app.tar.gz, and latest.json — those are for auto-update.

Linux

# Debian / Ubuntu
sudo apt install ./Usage.Monitor_*_amd64.deb

# Fedora / RHEL
sudo dnf install ./Usage.Monitor-*-1.x86_64.rpm

# AppImage
chmod +x Usage.Monitor_*.AppImage
./Usage.Monitor_*.AppImage

# Arch (from this repo)
cd packaging/arch
makepkg -si

macOS

Open the .dmg, drag Usage Monitor to Applications. Then open it from Applications (not from the DMG).

CI builds are ad-hoc signed (no Apple Developer ID). First launch may ask you to confirm an unidentified developer: right-click the app → Open. If Gatekeeper still says the app is damaged:

xattr -cr "/Applications/Usage Monitor.app"

Later GitHub Releases auto-updates do this themselves (no sudo, no extra notification). The first .dmg install can still need the command once.

The app is a menu-bar extra (no Dock icon). Left-click the status item for the detail popup; right-click for the menu (providers, start at login, quit). GUI apps do not inherit your shell PATH; the app prepends Homebrew and user bin dirs (/opt/homebrew/bin, /usr/local/bin, ~/.local/bin, …) so claude / omp resolve.

Quick Start (from source)

Rust + Node 20+.

npm install
npm run tauri

Or:

cd src-tauri
cargo run

Linux deps

sudo apt install libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev patchelf
npm install
npm run tauri

On Linux the popup opens from the tray menu (the panel eats the left-click).

How to Use

Action	What happens
Hover	Tooltip: usage % and reset times
Left-click (Windows / macOS)	Detail popup (toggle on macOS)
Double-click (Windows)	Quick action if configured
Right-click / Linux left-click	Source picker, Start at login, restart, quit
Escape / click outside	Close popup

Windows may hide new tray icons: Taskbar settings → Other system tray icons → Usage Monitor On.

Each popup bar: blue fill = used, white tick = elapsed time, red fill = usage ahead of the clock.

Configuration

Optional usage-monitor-settings.json (first match wins):

1. $CLAUDE_CONFIG_DIR/usage-monitor-settings.json when --config-dir / CLAUDE_CONFIG_DIR is set
2. Next to the executable (or project root from source)
3. ~/.claude/usage-monitor-settings.json

The app never creates this file on first run. Full key list: Configuration.

{
  "poll_interval": 180,
  "ninerouter_url": "http://localhost:20128",
  "icon_style": "number+bars",
  "source_id": "grok"
}

Building

npm install
cd src-tauri
cargo test --lib
npm run build

Outputs land in src-tauri/target/release/bundle/.

CI on every v* tag: Windows NSIS+MSI, Linux deb/rpm/AppImage (x64 + ARM64), macOS dmg (Apple Silicon + Intel). Arch: packaging/arch/PKGBUILD. See .github/workflows/release.yml.

Disclaimer

Independent project. Not created or endorsed by Anthropic, OpenAI, xAI, or Cursor. Product names are used only to describe compatibility.