QuotaBubble

Your AI usage limits, always in sight.

QuotaBubble is a small, frameless desktop widget that keeps the usage limits for your AI coding tools visible without opening a dashboard, terminal, or browser. It floats above your windows, fades to almost nothing when idle, and expands into a compact detail panel when you click it.

Features

• Frameless floating bubble — translucent, rounded, always on top, and it never steals keyboard focus.
• Fades away when idle — a configurable low opacity keeps it unobtrusive; hover to bring it back.
• Click to expand — see each usage window, the percentage used, and a live reset countdown.
• Drag anywhere — move it across monitors; the position is remembered.
• Tray icon — show/hide, settings, open logs, and quit.
• Resilient — refreshes every 5 minutes, caches the last good values, and keeps showing them (dimmed) through transient network or rate-limit errors.
• Local only — it reuses the credentials your tools already store and talks straight to the providers. No telemetry, no QuotaBubble server.

Supported providers

Providers are detected automatically. Enable or disable them in Settings; API keys are entered there and validated inline with a Test button. Antigravity and Copilot reuse their existing Windows Credential Manager or macOS Keychain sign-ins. Cursor reuses the IDE session token from state.vscdb or auth.json (or CURSOR_SESSION_TOKEN).

Install

Windows

With winget:

winget install Izzet.QuotaBubble

Or with Chocolatey:

choco install quotabubble

Or download the latest QuotaBubble-windows-x64.zip from the Releases page, unzip it, and run QuotaBubble.exe.

The binary is not code-signed yet, so Windows SmartScreen may warn you. Choose More info → Run anyway.

macOS

Download the matching disk image from the Releases page:

• QuotaBubble-macos-arm64.dmg for Apple Silicon Macs.
• QuotaBubble-macos-x64.dmg for Intel Macs.

Install or upgrade with Homebrew after adding the first-party tap:

brew install --cask izzet/tap/quotabubble

Open the disk image and drag QuotaBubble to Applications. The initial macOS builds are not yet Developer ID signed or notarized; Control-click the app, choose Open, then confirm the first-launch dialog. Signing and notarization will be added in a later release.

From source (Python 3.11+)

git clone https://github.com/izzet/quotabubble.git
cd quotabubble
uv tool install --editable .
quotabubble

You can also install it as a standalone command with pipx: pipx install quotabubble.

Usage

• Idle — a faint bubble; hover to make it fully visible.
• Click — expand the detail panel; click again to collapse.
• Drag — grab and move it anywhere, including across monitors.
• Right-click / tray — Settings, Open logs, Show/Hide, Quit.
• Launch at login — enable it in Settings.

Settings

Idle opacity, fade delay, refresh interval (default 5 minutes), show percentage used vs. remaining, launch at login, and which providers are visible.

Where things live

On Windows:

On macOS and Linux these map to the standard platform directories.

Development

uv sync
uv run ruff check src tests
uv run pytest -q
uv run pytest -q --cov=src/quotabubble --cov-report=term-missing  # with coverage

CI gates on coverage (currently 78% minimum, see [tool.coverage.report] in pyproject.toml) and uploads results to Codecov.

See AGENTS.md for architecture and contribution conventions. The provider layer (src/quotabubble/providers/) is pure Python behind a Provider protocol, and platform specifics live in src/quotabubble/platform/.

Status

Windows and macOS have native release artifacts. Claude, Codex, Cursor, OpenCode, DeepSeek, and OpenRouter work anywhere. Antigravity and Copilot support Windows Credential Manager and macOS Keychain; Linux credential support is still to come. API keys entered in Settings are stored in the OS credential store (Windows Credential Manager, macOS Keychain, Linux Secret Service) via keyring; if no OS keyring backend is available, they fall back to the local settings file.

License

MIT