QuotaGlass

Always-visible Claude + Codex usage on your Windows desktop. Draggable glass widget, radial-ring countdowns, custom-sound notifications, and a configurable alarm ladder (24 h / 12 h / 6 h / 3 h / 1 h / 30 m / 15 m / 5 m) so you know the moment your weekly quota renews.

QuotaGlass is the desktop companion to the AI-Usage_Tracker browser extension. The extension already handles the authenticated API path against claude.ai and chatgpt.com. QuotaGlass surfaces that data on your desktop as a floating widget with OS-native toasts, so you don't have to keep a tab open or pin the popup.

Features

• Floating glass widget — borderless, always-on-top, draggable, snaps to screen edges. Catppuccin Mocha by default, no pill backdrops, 8–12 px corner radii.
• Per-provider radial-ring countdowns — one card per Claude / Codex bucket, percent-used in the ring, time-to-reset in the center.
• OS toast notifications with custom sound — drop in any .wav, .mp3, .m4a, .aac, or .wma (WAV plays via SoundPlayer; everything else via WPF MediaPlayer / Media Foundation). Fires at user-configurable thresholds.
• Reset alarm ladder — pop a toast at 24 h, 12 h, 6 h, 3 h, 1 h, 30 m, 15 m, 5 m, and at-reset. Each tier is independently toggleable, and bucket toasts include Snooze 1h / Open analytics actions.
• Zero-state alert — special toast when a bucket hits 0% remaining (you've burned the whole window).
• Live data via native messaging + named pipe — the extension pipes snapshots into QuotaGlass's local daemon over chrome.runtime.connectNative; the widget also listens to a low-latency local named pipe for direct credential polling updates.
• Direct credential polling fallback — optional QuotaGlass.NMH.exe --poll-credentials reads Claude Code / Codex / Hermes credential files and writes snapshot.local-creds.json, then the widget merges both producers without card flicker.
• Multi-account support — schema v3 can render Claude / Codex primary and secondary accounts with short account labels in tooltips.
• Snapshot persistence — last-known usage cached to %LOCALAPPDATA%\QuotaGlass\snapshot.json, so the widget shows something useful even when the browser is closed.
• Settings panel — embedded, in-widget, with alarm, display, integration, and advanced sections. Includes alarm ladder, custom sounds, theme/high-contrast/system-theme mode, webhooks, and autostart.
• Embedded log panel — collapsed by default, surfaces NMH connection state and last fetch error if any.

How it works

┌────────────────────────────────────────────────────────────────┐
│  Chrome / Edge / Firefox                                       │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ AI-Usage_Tracker extension (existing)                    │  │
│  │  • Polls Claude /api/organizations/{org}/usage           │  │
│  │  • Polls Codex /backend-api/wham/usage                   │  │
│  │  • Captures SSE message_limit + ratelimit headers        │  │
│  │  • connectNative("com.sysadmindoc.quotaglass")           │  │
│  └────────────────────────┬─────────────────────────────────┘  │
└───────────────────────────┼────────────────────────────────────┘
                            │  stdin/stdout, 4-byte LE length
                            │  prefix + UTF-8 JSON
                            ▼
              ┌───────────────────────────────┐
              │  QuotaGlass.NMH.exe           │
              │  (.NET 9 console, ~12 KB)     │
              │  • reads bucket snapshots     │
              │  • atomically writes to       │
              │    %LOCALAPPDATA%\QuotaGlass  │
              │    \snapshot.json             │
              └────────────────┬──────────────┘
                               │  FileSystemWatcher
                               ▼
              ┌───────────────────────────────┐
              │  QuotaGlass.Widget.exe        │
              │  (.NET 9 WPF, always-on-top)  │
              │  • radial-ring countdowns     │
              │  • toast notifications        │
              │  • alarm-ladder scheduler     │
              └───────────────────────────────┘

Install

1. Install the AI-Usage_Tracker extension (Chrome / Edge / Brave / Firefox). The extension version that adds native-messaging support will be ≥ 0.2.0.
2. Download QuotaGlass-Setup-vX.Y.Z.exe from the Releases page.
3. Run the installer. Windows SmartScreen will prompt because v0.1.x binaries are unsigned — click More info → Run anyway. The installer:
   • Places the binaries in %LOCALAPPDATA%\Programs\QuotaGlass\.
   • Runs QuotaGlass.NMH.exe --register (writes HKCU keys for Chrome, Edge, Chromium, Firefox under Software\*\NativeMessagingHosts\com.sysadmindoc.quotaglass).
   • Drops a Start Menu shortcut with System.AppUserModel.ID = com.sysadmindoc.QuotaGlass.Widget (required for toast grouping in Action Center).
   • Adds an HKCU Run entry to autostart the widget on login (toggleable in Settings).
4. Reload the AI-Usage_Tracker extension in chrome://extensions/.
5. The widget launches automatically and pops a "QuotaGlass is in your tray" toast. Right-click the tray icon → Show widget.

Build from source

cd ~/repos/QuotaGlass
dotnet build QuotaGlass.sln -c Release
dotnet publish src/QuotaGlass.Widget/QuotaGlass.Widget.csproj -c Release -r win-x64 --self-contained false -o artifacts/publish/win-x64
dotnet publish src/QuotaGlass.NMH/QuotaGlass.NMH.csproj    -c Release -r win-x64 --self-contained false -o artifacts/publish/win-x64

For ARM64 (Surface Pro X / Snapdragon-X laptops), swap win-x64 → win-arm64.

Requires .NET 9 SDK (winget install Microsoft.DotNet.SDK.9).

To register the native messaging host against a local build:

artifacts/publish/win-x64/QuotaGlass.NMH.exe --register

To wipe local state during dev:

artifacts/publish/win-x64/QuotaGlass.NMH.exe --purge

To exercise the widget in isolation (without the extension/NMH chain):

dotnet run --project src/QuotaGlass.Widget -- --inject-fake-snapshot

Run tests

dotnet test QuotaGlass.sln -c Release

101 tests across the shared persistence/schema layer, NMH credential and diagnostics paths, widget snapshot merging, alarm scheduling, updater guards, toast-action parsing, and view-model regressions.

Project planning

• Roadmap
• Completed work
• Research report
• Archived research passes

OSS landscape & why this exists

See RESEARCH_REPORT.md for the current survey summary and docs/archive/research/ for historical evidence. TL;DR:

Option	Why it's not the fit
Rainmeter + HttpRequestPlugin	Skin DSL is awkward for stateful logic (alarm scheduler, snooze, fire-once). Re-solves auth from scratch. Loses the burn-rate + 30-day history work already in AI-Usage_Tracker.
Tauri / Electron port of the extension	Duplicates the JS data layer in a second runtime. ~150 MB install for a 32 px badge. Roadmap UC-01 in the extension explicitly parks this.
Direct Chromium cookie reads (DPAPI)	Chromium changed encryption mid-2024 + ongoing churn. Maintenance treadmill.
Standalone WPF widget polling the APIs directly	Means re-implementing Claude org discovery, SSE interception, and WHAM token handling. The extension already does it correctly.
Native messaging bridge + WPF widget (this project)	Single source of truth in the extension; widget is a thin display + notification surface; no second auth surface to maintain.

Privacy

• Nothing leaves your machine. No analytics, no telemetry, no remote servers.
• The native messaging channel is process-local stdin/stdout, and the low-latency named pipe is local-user scoped.
• Snapshots are written to your local %LOCALAPPDATA% folder. Delete the folder, delete the history.
• Source is fully auditable; no obfuscation, no minification.

License

MIT