quotabubble 0.1.2__tar.gz

quotabubble-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Test
+        run: uv run pytest -q

quotabubble-0.1.2/.github/workflows/pages.yml

@@ -0,0 +1,52 @@
+name: pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "website/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install
+        run: npm ci
+        working-directory: website
+
+      - name: Build
+        run: npm run build
+        working-directory: website
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

quotabubble-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: Where to publish
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.target }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Publish to TestPyPI
+        if: inputs.target == 'testpypi'
+        run: uv publish --publish-url https://test.pypi.org/legacy/ --trusted-publishing always
+
+      - name: Publish to PyPI
+        if: inputs.target == 'pypi'
+        run: uv publish --trusted-publishing always

quotabubble-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Build
+        run: uv run pyinstaller --noconfirm packaging/quotabubble.spec
+
+      - name: Package
+        shell: pwsh
+        run: Compress-Archive -Path dist/QuotaBubble/* -DestinationPath QuotaBubble-windows-x64.zip
+
+      - name: Publish release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: QuotaBubble-windows-x64.zip

quotabubble-0.1.2/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+.env
+
+# Local reference clones (not part of the project)
+external/
+.wakatime-project

quotabubble-0.1.2/AGENTS.md

@@ -0,0 +1,25 @@
+# QuotaBubble — agent guidelines
+
+## Workflow
+
+- **Never commit directly to `main`.** Create a branch per item: `feat/…`, `fix/…`, `chore/…`, `docs/…`.
+- Push the branch and **open a pull request** describing the change.
+- **Wait for review.** Address review comments by pushing follow-up commits to the same branch.
+- Merge **only after explicit approval**, and **never squash-merge** — use a merge commit (default).
+
+## Development
+
+- Package manager: `uv`.
+- Lint: `uv run ruff check src tests`.
+- Test: `uv run pytest -q`.
+- Providers live in `src/quotabubble/providers/` behind the `Provider` protocol; they must not import Qt.
+- Platform-specific behavior (window flags, credential stores, autostart) lives in `src/quotabubble/platform/`.
+- The UI (`src/quotabubble/ui/`) renders `UsageSnapshot` objects and must not perform I/O or HTTP itself.
+
+## Runtime notes
+
+- Config: `%LOCALAPPDATA%\quotabubble\settings.json`.
+- Last-good cache: `%LOCALAPPDATA%\quotabubble\Cache\last_good.json`.
+- Logs: `%LOCALAPPDATA%\quotabubble\Logs\quotabubble.log` (rotating).
+- Only one instance runs; a second launch re-shows the first.
+- Poll interval defaults to 5 minutes; transient errors fall back to the last-good snapshot.

quotabubble-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 izzet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quotabubble-0.1.2/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: quotabubble
+Version: 0.1.2
+Summary: A lightweight cross-platform floating widget that shows AI usage quotas.
+Project-URL: Homepage, https://izzet.github.io/quotabubble/
+Project-URL: Repository, https://github.com/izzet/quotabubble
+Project-URL: Issues, https://github.com/izzet/quotabubble/issues
+Project-URL: Changelog, https://github.com/izzet/quotabubble/releases
+Author: izzet
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,antigravity,claude-code,codex,copilot,deepseek,desktop-widget,openrouter,pyside6,quota,usage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.12
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyside6>=6.7
+Description-Content-Type: text/markdown
+
+# 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.
+
+<p align="center">
+  <img src="https://izzet.github.io/quotabubble/screenshot-compact.png?v=2" width="260" alt="Idle bubble">
+  <img src="https://izzet.github.io/quotabubble/screenshot-expanded.png?v=2" width="300" alt="Expanded detail">
+</p>
+
+## 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
+
+| Provider | Authentication |
+| --- | --- |
+| Claude Code | `~/.claude/.credentials.json` |
+| Codex | `~/.codex/auth.json` |
+| Google Antigravity | Windows Credential Manager (`gemini:antigravity`) |
+| GitHub Copilot | Windows Credential Manager (`…copilot-cli`) |
+| DeepSeek | API key |
+| OpenRouter | API key |
+
+Providers are detected automatically. Enable or disable them in Settings; API keys are entered there and validated inline with a **Test** button. On Windows, Antigravity and Copilot read their existing sign-ins from Credential Manager.
+
+## Install
+
+### Windows
+
+Download the latest `QuotaBubble-windows-x64.zip` from the [Releases page](https://github.com/izzet/quotabubble/releases), unzip it, and run `QuotaBubble.exe`.
+
+> The binary is not code-signed yet, so Windows SmartScreen may warn you. Choose **More info → Run anyway**.
+
+### From source (Python 3.11+)
+
+```bash
+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](https://pipx.pypa.io/): `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:
+
+| Path | Purpose |
+| --- | --- |
+| `%LOCALAPPDATA%\quotabubble\settings.json` | Settings |
+| `%LOCALAPPDATA%\quotabubble\Cache\last_good.json` | Last-good snapshots |
+| `%LOCALAPPDATA%\quotabubble\Logs\quotabubble.log` | Rotating log |
+
+On macOS and Linux these map to the standard platform directories.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check src tests
+uv run pytest -q
+```
+
+See [AGENTS.md](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 is the primary, fully supported platform. Claude, Codex, DeepSeek, and OpenRouter work anywhere; Antigravity and Copilot currently use the Windows credential store and need macOS/Linux implementations. API keys are stored in the local settings file for now — moving them to the OS keyring is tracked in [#3](https://github.com/izzet/quotabubble/issues/3).
+
+## License
+
+[MIT](LICENSE)

quotabubble-0.1.2/README.md

@@ -0,0 +1,94 @@
+# 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.
+
+<p align="center">
+  <img src="https://izzet.github.io/quotabubble/screenshot-compact.png?v=2" width="260" alt="Idle bubble">
+  <img src="https://izzet.github.io/quotabubble/screenshot-expanded.png?v=2" width="300" alt="Expanded detail">
+</p>
+
+## 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
+
+| Provider | Authentication |
+| --- | --- |
+| Claude Code | `~/.claude/.credentials.json` |
+| Codex | `~/.codex/auth.json` |
+| Google Antigravity | Windows Credential Manager (`gemini:antigravity`) |
+| GitHub Copilot | Windows Credential Manager (`…copilot-cli`) |
+| DeepSeek | API key |
+| OpenRouter | API key |
+
+Providers are detected automatically. Enable or disable them in Settings; API keys are entered there and validated inline with a **Test** button. On Windows, Antigravity and Copilot read their existing sign-ins from Credential Manager.
+
+## Install
+
+### Windows
+
+Download the latest `QuotaBubble-windows-x64.zip` from the [Releases page](https://github.com/izzet/quotabubble/releases), unzip it, and run `QuotaBubble.exe`.
+
+> The binary is not code-signed yet, so Windows SmartScreen may warn you. Choose **More info → Run anyway**.
+
+### From source (Python 3.11+)
+
+```bash
+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](https://pipx.pypa.io/): `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:
+
+| Path | Purpose |
+| --- | --- |
+| `%LOCALAPPDATA%\quotabubble\settings.json` | Settings |
+| `%LOCALAPPDATA%\quotabubble\Cache\last_good.json` | Last-good snapshots |
+| `%LOCALAPPDATA%\quotabubble\Logs\quotabubble.log` | Rotating log |
+
+On macOS and Linux these map to the standard platform directories.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check src tests
+uv run pytest -q
+```
+
+See [AGENTS.md](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 is the primary, fully supported platform. Claude, Codex, DeepSeek, and OpenRouter work anywhere; Antigravity and Copilot currently use the Windows credential store and need macOS/Linux implementations. API keys are stored in the local settings file for now — moving them to the OS keyring is tracked in [#3](https://github.com/izzet/quotabubble/issues/3).
+
+## License
+
+[MIT](LICENSE)

quotabubble-0.1.2/assets/.gitkeep

@@ -0,0 +1 @@
+

quotabubble-0.1.2/packaging/launcher.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from quotabubble.app.main import main
+
+if __name__ == "__main__":
+    main()

quotabubble-0.1.2/packaging/quotabubble.spec

@@ -0,0 +1,42 @@
+# -*- mode: python ; coding: utf-8 -*-
+
+from pathlib import Path
+
+ROOT = Path(SPECPATH).parent
+
+a = Analysis(
+    [str(Path(SPECPATH) / "launcher.py")],
+    pathex=[str(ROOT / "src")],
+    binaries=[],
+    datas=[],
+    hiddenimports=[],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    noarchive=False,
+)
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    [],
+    exclude_binaries=True,
+    name="QuotaBubble",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=False,
+    console=False,
+    icon=str(ROOT / "assets" / "quotabubble.ico"),
+)
+
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.datas,
+    strip=False,
+    upx=False,
+    name="QuotaBubble",
+)

quotabubble-0.1.2/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "quotabubble"
+version = "0.1.2"
+description = "A lightweight cross-platform floating widget that shows AI usage quotas."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "izzet" }]
+keywords = [
+    "ai",
+    "usage",
+    "quota",
+    "claude-code",
+    "codex",
+    "copilot",
+    "antigravity",
+    "deepseek",
+    "openrouter",
+    "desktop-widget",
+    "pyside6",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: X11 Applications :: Qt",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "httpx2>=2.12",
+    "platformdirs>=4.0",
+    "pydantic>=2.0",
+    "pyside6>=6.7",
+]
+
+[project.gui-scripts]
+quotabubble = "quotabubble.app.main:main"
+
+[project.urls]
+Homepage = "https://izzet.github.io/quotabubble/"
+Repository = "https://github.com/izzet/quotabubble"
+Issues = "https://github.com/izzet/quotabubble/issues"
+Changelog = "https://github.com/izzet/quotabubble/releases"
+
+[dependency-groups]
+dev = [
+    "pyinstaller>=6.0",
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quotabubble"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = ["external"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

quotabubble-0.1.2/scripts/make_icon.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import os
+import struct
+from pathlib import Path
+
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+
+from PySide6.QtCore import QBuffer
+from PySide6.QtGui import QGuiApplication
+
+from quotabubble.ui.icon import _pixmap
+
+SIZES = (16, 24, 32, 48, 64, 128, 256)
+
+
+def _png_bytes(size: int) -> bytes:
+    buffer = QBuffer()
+    buffer.open(QBuffer.OpenModeFlag.WriteOnly)
+    _pixmap(size).toImage().save(buffer, "PNG")
+    return bytes(buffer.data())
+
+
+def build_ico(path: Path) -> None:
+    images = [(size, _png_bytes(size)) for size in SIZES]
+    header = struct.pack("<HHH", 0, 1, len(images))
+    offset = 6 + 16 * len(images)
+    entries = b""
+    data = b""
+    for size, blob in images:
+        dimension = 0 if size >= 256 else size
+        entries += struct.pack("<BBBBHHII", dimension, dimension, 0, 0, 1, 32, len(blob), offset)
+        offset += len(blob)
+        data += blob
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(header + entries + data)
+
+
+def main() -> None:
+    QGuiApplication([])
+    target = Path(__file__).resolve().parent.parent / "assets" / "quotabubble.ico"
+    build_ico(target)
+    print(f"wrote {target}")
+
+
+if __name__ == "__main__":
+    main()

quotabubble-0.1.2/src/quotabubble/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

quotabubble-0.1.2/src/quotabubble/__main__.py

@@ -0,0 +1,4 @@
+from quotabubble.app.main import main
+
+if __name__ == "__main__":
+    main()

quotabubble-0.1.2/src/quotabubble/app/__init__.py

@@ -0,0 +1 @@
+