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

Kimi Code runs separate regional services (kimi.com and kimi.ai): the login is only ever sent to the host the CLI itself is configured for (override with KIMI_CODE_BASE_URL). QuotaBubble never refreshes the CLI's login; when it expires, open Kimi Code to renew it.

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 OS keychain sign-ins, including Linux Secret Service. 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 with Scoop:

scoop bucket add izzet https://github.com/izzet/scoop-bucket
scoop install izzet/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.

Ubuntu GNOME

Download QuotaBubble-linux-amd64.deb from the matching GitHub Release, then install it:

sudo apt install ./QuotaBubble-linux-amd64.deb
gnome-extensions enable quotabubble@izzet.dev

The extension activates the user-session service on demand. Open quotabubble-settings to configure providers, notifications, and launch at login.

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 80% 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, macOS, and Ubuntu GNOME 24.04 (amd64) have native release artifacts. Claude, Codex, Cursor, OpenCode, DeepSeek, OpenRouter, Kimi Code, Z.ai, and Grok work anywhere. Zed currently works on Windows only. Antigravity and Copilot reuse Windows Credential Manager, macOS Keychain, and Linux Secret Service credentials. API keys entered in Settings are stored in the OS credential store via keyring; if no OS keyring backend is available, they fall back to the local settings file.

License

MIT