If you pay for multiple AI subscriptions and frequently check your usage, AI Gauge might help. It shows session and weekly usage, reset times, account balances, and spend in a compact always-visible view, so you can get the most out of what you're paying for.
Compact monitor for Claude.ai, ChatGPT Codex, GitHub Copilot, and OpenRouter usage. Manual + auto refresh, with a platform-native UI on each OS:
Windows / Linux— always-on-top draggable frameless widget plus a system-tray icon.** macOS**— Stats-style menu-bar item (● 42% ● 78% ● 15%
); the panel opens as a popover when you click it.
Requires Python 3.11+.Secrets live in the OS-native credential store (Windows Credential Manager / DPAPI, macOS Keychain, Linux Secret Service). Auto-start uses the platform's standard mechanism (Run key / LaunchAgent /~/.config/autostart
).
Current version: 0.5.9. See CHANGELOG.md for release notes.
AI Gauge is an independent open-source project and unofficial local desktop utility. It is not affiliated with Anthropic, OpenAI, GitHub, Microsoft, OpenRouter, or any other provider. Provider pages and APIs may change without notice.
Windows / Linux — always-on-top floating widget, in full panel and collapsed pill modes:
macOS — Stats-style menu-bar item with per-provider tinted dots; click to open the panel as a popover:
Pre-built binaries for each release are published on the Releases page. Pick the archive for your OS, extract, and run:
| OS | Archive | Run |
|---|---|---|
| Windows | ai-gauge-<version>-windows.zip |
|
extract, run ai-gauge.exe |
||
| macOS | ai-gauge-<version>-macos.tar.gz |
|
extract, drag ai-gauge.app to Applications |
||
| Linux | ai-gauge-<version>-linux.tar.gz |
|
extract, run ./ai-gauge/ai-gauge |
SHA256 sums are published alongside each archive. Builds are unsigned — see the first-launch warnings section below for SmartScreen / Gatekeeper handling.
Windows (PowerShell):
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .[dev]
.\.venv\Scripts\python.exe -m aigauge
macOS / Linux (bash):
python3 -m venv .venv
./.venv/bin/python -m pip install -e '.[dev]'
./.venv/bin/python -m aigauge
On first launch the widget appears with enabled provider tiles. Claude and Codex use a Sign in flow; GitHub Copilot and OpenRouter are configured from Settings with API credentials. Open Settings to disable providers you don't use or to add more Claude/Codex accounts.
| Provider | Setup |
|---|---|
| Claude.ai | |
| Sign in (recommended): opens an embedded browser. Don't click "Continue with Google" — Google refuses to authenticate inside embedded browsers. If your account is Google-linked, just type that same email into the Enter your email box and use the magic link sent to your inbox. Paste cookie: fallback if magic-link is unavailable; see below. Add extra Claude subscriptions from Settings → Claude. | |
| ChatGPT Codex | |
| Same as Claude — use email + magic link in the embedded browser, or paste cookie as a fallback. If your OpenAI account routes through Google or a passkey, use Paste cookie; embedded browsers often cannot complete those flows. Add extra Codex subscriptions from Settings → Codex. | |
| GitHub Copilot | |
| Create a fine-grained PAT at | |
| Account permissions → Plan → Read. Paste into Settings; set your monthly AI credit allowance (Pro=1,500, Pro+=7,000, Max=20,000). If Copilot is billed through an organization, enter the billing org and use a token/account with org billing access and Organization permissions → Administration → Read. | |
| OpenRouter | |
| Create an inference API key at | |
Claude and Codex can track more than one subscription at a time. Open Settings → Claude or Settings → Codex, click Add another, give the account a short name, then use Sign in or Paste cookie for that specific row. The default account displays as Claude
or Codex
; named accounts display as Claude (Work)
, Codex (Account 2)
, etc.
The General tab controls provider groups. If Claude is checked, all configured Claude accounts appear; if Codex is checked, all configured Codex accounts appear. Secondary accounts can be removed from their provider tab. Each Claude/Codex account uses separate cookie storage, browser profile data, widget tile state, and history records.
Sessions persist between runs under the per-OS app-data directory:
| OS | App data | Secrets backend |
|---|---|---|
| Windows | %APPDATA%/ai-gauge/ |
|
Credential Manager (GitHub PAT + OpenRouter keys) + DPAPI-encrypted secrets.dat (cookies, since the Credential Manager blob limit is too small for ChatGPT JWTs) |
||
| macOS | ~/Library/Application Support/ai-gauge/ |
|
| Login Keychain | ||
| Linux | ~/.config/ai-gauge/ |
|
| Secret Service (GNOME Keyring / KWallet) |
AI Gauge does not include telemetry or a backend service. Provider requests are made from the local app to the configured providers. See SECURITY.md for security and privacy notes.
If the embedded-browser sign-in doesn't work for you (e.g. your account requires Google sign-in, passkey authentication, or you can't use the magic-link path), copy your existing session cookie from your normal browser into the app. Cookies last weeks before they need re-pasting.
- Sign into
https://claude.ai(orhttps://chatgpt.com) inChrome / Edge / Firefox as you normally do. - For ChatGPT, press
F12→** Network**, reload the page, click a
chatgpt.com
request, and copy the fullRequest Headers → Cookie: value. This includes split session cookies plus companion auth cookies such as__Secure-oai-is
. - For Claude, press
F12→** Network**, reloadhttps://claude.ai/new#settings/usage
, click aclaude.ai
request, and copy the fullRequest Headers → Cookie: value. It must includesessionKey
. - In the app: Settings → Claude or Settings → Codex → click Paste cookie next to the account, paste, Save.
Windows / Linux: the widget floats above other windows by default. Drag anywhere to move; close (✕) hides to tray. Right-click the tray icon for Refresh / Settings / Quit. Left-click toggles widget visibility. Tray icon turns yellow ≥75% / red ≥90% based on the highest tile reading.macOS: the menu-bar item shows tinted status dots for enabled provider/account tiles. Click it to open the panel as a popover; click outside to dismiss. Right-click for the same Refresh / Settings / Quit menu.Linux without a system tray(stock GNOME): the floating widget stays visible and serves the same Show / Refresh / Settings / Quit menu via right-click on the widget.Collapse / expand: click the− button in the widget header to shrink to the compact pill view. Enabled provider/account chips wrap onto additional rows when needed, with named secondary Claude/Codex accounts using just the account name to save space.Hide unused providers: uncheck Claude / Codex / Copilot / OpenRouter in Settings to remove their group from the widget — useful if you only use one or two of them.- Auto-refresh is adaptive: manual refresh or changed usage enters the active cadence, then unchanged results back off toward the configured max interval. Defaults are 5 min active and 60 min idle max.
- Enable Start at login in Settings if you want it to run as a daily utility.
For most users the pre-built downloads are easier — this section is for building locally or for maintainers cutting releases. The build machine needs Python 3.11+ and a .venv
with pip install -e .[dev]
already run; the resulting binary does not require Python on the target machine.
| OS | Command | Output |
|---|---|---|
| Windows | .\build.ps1 |
|
dist/ai-gauge/ai-gauge.exe |
||
| macOS | ./build.sh |
|
dist/ai-gauge.app |
||
| Linux | ./build.sh |
|
dist/ai-gauge/ai-gauge |
Tagged commits matching v*
automatically run the release workflow, which builds all three platforms in CI and uploads them as a draft GitHub Release for the maintainer to publish.
Bundles are ~150-200 MB because the Chromium runtime ships inside. User data still lives outside the bundle, under the per-OS app-data directory.
For a single-file binary (slower first launch), pass -OneFile
(PowerShell) or --onefile
(bash). On macOS the .app
bundle is recommended over the single-file form.
First-launch warnings on signed-OS-bundle systems — release artifacts are unsigned:
Windows: SmartScreen → "More info" → "Run anyway".macOS: Gatekeeper blocks on first launch. Either right-click the.app
→ Open the first time, or runxattr -dr com.apple.quarantine ai-gauge.app
once.Linux: no signing layer; just makeai-gauge
executable if it isn't already.
See RELEASING.md for maintainer release steps.
.\.venv\Scripts\python.exe -m pytest # Windows
./.venv/bin/python -m pytest # macOS / Linux
Tests cover: config round-trip, Copilot and OpenRouter REST helpers (with mocked HTTP), widget behavior, and snapshot models. Provider scrapers (Claude/Codex) require a live browser session and are validated manually.
Bug reports, provider-layout fixes, and PRs are welcome. See CONTRIBUTING.md for environment setup, test commands, and the issue templates to use.
Why an embedded browser instead of reading Chrome cookies? Chrome 127+ added App-Bound Encryption (mid-2024) that blocks every external Python library from decrypting Chrome/Edge cookies. Owning the browser session ourselves is the only reliable workaround.Claude / Codex layouts may change. If a provider tile shows "error" after a UI update upstream, the page-extractor JS insrc/aigauge/providers/{claude,codex}.py
needs adjusting — the rest of the app keeps working.- The Copilot REST endpoint returns the
current calendar monthof billing usage. The widget tracks gross AI credits consumed against the included allowance; net quantity/amount is only the billable overage. Reset is computed as the 1st of the next month. GitHub does not currently expose a reliable personal-plan allowance field, so Settings uses a plan dropdown with a Custom fallback. Annual/request-based accounts are handled with a legacy premium-request fallback. Copilot usage lags upstream. The Copilot REST endpoint updates noticeably slower than Claude or Codex — credit counts can take hours to reflect recent activity. The widget shows the most recent value GitHub returns; treat the Copilot tile as a trailing indicator, not real-time.Copilot AI credits. GitHub moved Copilot from per-request quotas to token-based AI credits. Code completions and next edit suggestions remain included for paid plans, while Chat, CLI, cloud agent, Spaces, Spark, and third-party coding agents consume AI credits. The app shows the credit usage GitHub returns; if your account is org-billed, enter the billing organization so AI Gauge reads the organization billing pool.OpenRouter uses two key types. The inference key is used for/key
spend data. The management key is required for/credits
account balance and/activity
model history. Without a management key, AI Gauge still shows key-level spend but cannot show balance or model activity.OpenRouter time windows are UTC. Today/month spend come from OpenRouter's current UTC day and month fields. Model activity comes from OpenRouter's default/activity
history window: the last 30 completed UTC days, excluding the current UTC day.