Quota Menubar Tauri

Tauri v2 menubar/tray app for monitoring Claude and Codex quota usage on macOS and Windows.

Core Behavior

• Menubar tray icon is created at startup and stays resident.
• Left click tray icon toggles the quota panel.
• Right click menu provides Show / Hide Window and Quit.
• Claude and Codex are separated into independent tabs and polling flows.
• Quota polling runs every 60 seconds in the background, with adaptive backoff to 5 minutes on 429.
• OAuth token is proactively refreshed before expiry (30-minute buffer) using the keychain expiresAt field.
• macOS tray mode disables webview background throttling so hidden windows keep polling.
• Tray percentage now represents used quota (not remaining quota).

Quota Semantics

• Claude tray value:
  • prefers weekly window (weeklyTotal)
  • falls back to max of weeklyOpus and weeklySonnet
  • falls back to current session usage
• Codex tray value:
  • prefers weekly window (secondary_window.used_percent)
  • falls back to short window (primary_window.used_percent)

Project Layout

• Frontend:
  • src/App.tsx
  • src/components/*
  • src/services/backend.ts (single Tauri invoke gateway)
  • src/types/models.ts (shared frontend contracts)
• Backend (Rust):
  • src-tauri/src/commands.rs (thin command boundary)
  • src-tauri/src/domain/models.rs (serialized contracts)
  • src-tauri/src/services/claude.rs
  • src-tauri/src/services/codex.rs
  • src-tauri/src/services/tray.rs
  • src-tauri/src/services/tray_icon.rs
  • src-tauri/src/services/window.rs
  • src-tauri/src/services/link.rs

Requirements

• macOS or Windows
• Bun (recommended package manager/runtime)
• Rust toolchain
• Tauri prerequisites installed

Development

bun install
bun run tauri dev

Build

bun run tauri build --bundles app

macOS app bundle output:

src-tauri/target/release/bundle/macos/Quota Menubar Tauri.app

Windows installer output:

src-tauri/target/release/bundle/msi/ src-tauri/target/release/bundle/nsis/

Install / Run

macOS:

./scripts/stop_app.sh
./scripts/install_app.sh
./scripts/run_app.sh

Or one-shot restart after rebuild:

./scripts/reinstall_and_run.sh

Windows:

• Build installer: bun run tauri build --bundles msi,nsis
• Install from generated .msi or .exe

Verification Commands

bun run build
cd src-tauri && cargo check
cd src-tauri && cargo test

Troubleshooting

• Tray icon flashes then disappears:
  • check menu bar manager hidden area (Ice/Bartender)
  • ensure app is not auto-grouped into hidden extras
• No quota data:
  • Claude on macOS: ensure Claude Code login exists in macOS Keychain (claude login)
  • Claude on Windows/Linux: set CLAUDE_CODE_OAUTH_TOKEN environment variable
  • Codex: ensure ~/.codex/auth.json is valid and not expired
• Token expired after long idle (24h+):
  • App auto-refreshes using the keychain refresh token — no manual action needed
  • If refresh fails, run claude login in terminal
• Persistent 429 rate limiting:
  • App uses User-Agent: claude-code/* header to avoid strict rate limit buckets
  • On 429, app serves stale cached data and backs off polling to 5 minutes
• Codex token expired:
  • run codex login flow again

License

Private/internal project (update as needed before open-source release).