QuotaBar

QuotaBar is a Tauri v2 menubar app for monitoring Claude Code, Codex, Cursor, Grok Build, and Antigravity usage. It shows live quota windows, per-provider tray indicators, and local cost estimates from on-device logs.

Website: https://majiayu000.github.io/quotabar/

Features

• Overview: remaining quota and per-service freshness, with optional usage details. The overview count is connected services, not an aggregate quota percentage.
• High-usage tips explain remaining quota and reset timing; stale data does not produce usage advice.
• Provider switcher: overview plus full-name cards for Claude, Codex, Cursor, Grok, and Antigravity.
• Claude quota: 5-hour, 7-day, Opus, Sonnet, and Claude Design windows.
• Codex quota: short and weekly ChatGPT usage windows, local weekly pace and API-equivalent value estimates, and an exhausted-week layout that keeps the last estimate and a clickable bonus reset. Observed usage is valued at standard API token prices; the full-week value is a rough extrapolation from an official quota snapshot, not a bill or an official dollar allowance. Fast-mode premiums and purchased credits are not represented by this estimate.
• Cursor quota: signed-in Cursor usage and request-limit windows when session data is available.
• Grok quota: SuperGrok weekly (or monthly) credits pool, product mix for Build/Chat/Imagine/Voice/API, extra credits, and an API-equivalent value estimate from ccstats' durable inference ledger.
• Antigravity panel: placeholder provider status while quota tracking is pending.
• Local cost tracking: today, week, and month estimates for Claude Code, Codex, and Cursor.
• Per-provider tray icons: independent menu bar indicators for supported providers.
• Tray controls: enable or hide each tray while keeping at least one entry point.
• Settings view: theme, macOS Hide Dock, Launch at Login, All / single-service presets, Limits vs Alerts, and per-provider tray controls. Launch at Login uses the OS login item rather than a local storage key.
• Notifications: 80%, 95%, 100%, unused bonus reset, and bonus-expiry alerts.
• Background polling: refreshes every 60 seconds, backs off to 5 minutes on 429, and backs off to 1 hour on Claude auth failures.
• Read-only Claude OAuth: reads Claude Code credentials from the correct source, but never refreshes or writes OAuth tokens.
• Read-only Grok auth: reads ~/.grok/auth.json, but never refreshes or writes tokens.
• Hidden-window polling: disables macOS webview throttling so menubar mode keeps working.

Demo Proof

This v0.4.0 screenshot was refreshed on 2026-08-31 from the production React UI in browser preview without a Tauri desktop backend. It intentionally shows the default unavailable-backend state and includes no provider quota values, account identifiers, tokens, cookies, or sessions. Desktop widget and notification visuals are static design previews only until a runtime implementation ships. See docs/demo-proof.md for the capture scope and refresh steps.

Quota Semantics

• Claude tray value:
  • uses the hottest Claude window (same ranking as the overview/header)
  • includes the 5-hour session, 7-day All models (weeklyTotal), Opus, Sonnet, Design, and Fable 5 windows
  • keeps weeklyTotal as a labeled card, not the implicit tray or 80/95 alert headline
• Codex tray value:
  • prefers secondary_window.used_percent
  • falls back to primary_window.used_percent
• Cursor tray value:
  • prefers Cursor Models (autoPercent)
  • falls back to the overall Cursor quota percentage
• Grok tray value:
  • uses the shared SuperGrok credits pool percent (creditUsagePercent)
• Antigravity tray value:
  • shows provider availability while usage tracking is pending
• Tray percentages represent used quota, not remaining quota.

Project Layout

• Frontend:
  • src/App.tsx
  • src/components/*
  • src/services/backend.ts
  • src/services/service_meta.ts
  • src/services/tray_visibility.ts
  • src/types/models.ts
  • src/utils/*
• Backend:
  • src-tauri/src/commands.rs
  • src-tauri/src/domain/models.rs
  • src-tauri/src/services/claude.rs
  • src-tauri/src/services/codex.rs
  • src-tauri/src/services/cursor.rs
  • src-tauri/src/services/grok.rs
  • src-tauri/src/services/antigravity.rs
  • src-tauri/src/services/cost.rs
  • src-tauri/src/services/http.rs
  • src-tauri/src/services/tray.rs
  • src-tauri/src/services/tray_icon.rs
  • src-tauri/src/services/window.rs
• Release notes:
  • CHANGELOG.md
  • docs/release.md

Requirements

• macOS, Windows, or Linux
• Node.js with npm
• Rust toolchain
• Tauri prerequisites installed
• Claude Code login for Claude quota and cost data
• Codex login for Codex quota and cost data
• Cursor sign-in or CURSOR_SESSION_TOKEN for Cursor quota data
• Grok Build login (grok login) for Grok quota data
• Antigravity installed for Antigravity provider status

Development

QuotaBar opens a resizable desktop workspace with Overview, Quota, Usage, History, Sources, and Settings. The original provider tray panels remain available independently. Closing the workspace keeps tray monitoring running; Quit exits the application.

Local analytics use one filtered ccstats report for summaries, projects, sessions, daily/hourly history, activity, and period comparisons. Missing source data and incomplete pricing are shown explicitly. API-equivalent estimates are not subscription bills. Session titles come from existing source metadata or local manual names, with no model summarization. JSON/SVG summary exports omit session titles and paths.

The latest matching report is cached locally for quick startup while fresh analysis runs in the background. First-run loading has a reduced-motion-aware animation. Invalid Claude credentials require login before a quota request; failed reads wait for a manual recheck, with rate-limit deadlines still applied.

The repositories remain separate. This checkout contains an immutable SDK source archive with its upstream commit and SHA-256 in vendor/ccstats-sdk.json. npm run sdk:prepare verifies and extracts it; no sibling checkout is needed. SDK development can refresh the archive with npm run sdk:update when a ccstats checkout is beside this repository.

npm ci
npm run sdk:prepare
npm run tauri dev

Build

Frontend and Rust verification:

npm ci
npm run release:check
npm test
npm run build
cargo fmt --manifest-path src-tauri/Cargo.toml --check
cargo check --manifest-path src-tauri/Cargo.toml
cargo test --manifest-path src-tauri/Cargo.toml

Local macOS app bundle:

npm run tauri build -- --bundles app

src-tauri/target/release/bundle/macos/QuotaBar.app

Downloadable release bundles:

# macOS, for the current host architecture
npm run tauri build -- --bundles dmg

# Windows
npm run tauri build -- --bundles msi,nsis

# Linux
npm run tauri build -- --bundles appimage

Expected output locations:

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

Release Artifacts

The latest published release is available from GitHub Releases.

The v0.4.0 Apple Silicon and Intel macOS artifacts are unsigned and not notarized. macOS may require users to approve the app in Privacy & Security before first launch. Future public macOS candidates must pass the repository's opt-in Developer ID signing and notarization workflow; unsigned workflow artifacts remain tester builds.

Release candidates should be built by the release-artifacts GitHub Actions workflow or from a clean checkout, then attached manually to the matching GitHub release only after final human approval. The workflow uploads build artifacts and SHA-256 manifests for inspection; it does not publish a GitHub Release. See docs/release.md for the release checklist and signing-secret requirements.

Install / Run

With no saved panel preferences, the switcher shows detected services and keeps them accessible if a connection later fails. Use Add service for setup, or Settings to choose providers manually.

On first launch, Overview shows detected connections and instructions for signing in through each provider. Use Check connection after signing in. QuotaBar reads existing local sign-ins; it does not manage login or refresh tokens. Antigravity quota tracking is still pending.

For normal use, download the current installer from GitHub Releases. For development, install from a local build.

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:

• Download the .msi or .exe from GitHub Releases.
• Build installer: npm run tauri build -- --bundles msi,nsis
• Install from the generated .msi or .exe

Linux x64:

• Download the .AppImage from GitHub Releases.
• Make it executable: chmod +x QuotaBar_*.AppImage
• Run it: ./QuotaBar_*.AppImage

Verification

npm run release:check
npm test
npm run build
cargo fmt --manifest-path src-tauri/Cargo.toml --check
cargo check --manifest-path src-tauri/Cargo.toml
cargo test --manifest-path src-tauri/Cargo.toml
npm run tauri build -- --bundles app

Limitations

• QuotaBar reads local provider auth state; it does not manage provider login flows.
• Claude quota depends on Claude Code OAuth credentials and Anthropic's current usage response shape.
• Codex quota depends on ~/.codex/auth.json and ChatGPT usage windows returned by the current backend API.
• Cursor quota requires Cursor sign-in or CURSOR_SESSION_TOKEN.
• Antigravity support currently reports provider availability only; quota windows are not exposed yet.
• Cost estimates are derived from local logs and may be empty until provider tools have written usage history.

Troubleshooting

• Tray icon flashes then disappears:
  • check menu bar manager hidden area, such as Ice or Bartender
  • ensure the app is not auto-grouped into hidden extras
• No Claude quota data:
  • macOS: ensure Claude Code login exists in Keychain with claude login
  • Windows/Linux: set CLAUDE_CODE_OAUTH_TOKEN
  • if Claude auth fails, re-login with Claude Code and click Refresh
• No Codex quota data:
  • ensure ~/.codex/auth.json is valid
  • run the codex login flow again if the token expired
• No Cursor quota data:
  • sign in to Cursor
  • or set CURSOR_SESSION_TOKEN
• Antigravity quota is pending:
  • Antigravity support currently exposes provider status, not quota windows
• Persistent 429 rate limiting:
  • QuotaBar uses a Claude Code user agent and serves stale cached data when available
  • polling backs off to 5 minutes after 429 responses
• Cost data is empty:
  • local logs may not exist yet
  • costs are estimated offline from local Claude/Codex logs via ccstats

Support and Security

• Bugs and feature requests: use GitHub issues.
• Security or credential exposure: use GitHub private security advisories. Do not paste provider tokens, cookies, session files, or local auth material into public issues.
• Contributor setup and expectations: see CONTRIBUTING.md.
• Security scope and reporting: see SECURITY.md.

License

MIT