Show HN: AI Gauge, a desktop monitor for Claude/Codex/Copilot usage limits

Notifications You must be signed in to change notification settings

Fork 0

Star 3

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

49 Commits

49 Commits

.github

.github

docs/screenshots

docs/screenshots

src/aigauge

src/aigauge

tests

tests

tools

tools

.gitignore

.gitignore

AI Gauge-datasheet.md

AI Gauge-datasheet.md

CHANGELOG.md

CHANGELOG.md

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE

LICENSE

README.md

README.md

RELEASING.md

RELEASING.md

SECURITY.md

SECURITY.md

build.ps1

build.ps1

build.sh

build.sh

pyinstaller_entry.py

pyinstaller_entry.py

pyproject.toml

pyproject.toml

Repository files navigation

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.

Screenshots

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:

Settings dialog

Download

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--windows.zip extract, run ai-gauge.exe

macOS ai-gauge--macos.tar.gz extract, drag ai-gauge.app to Applications

Linux ai-gauge--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.

Run from source

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.

First-time setup per provider

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 https://github.com/settings/personal-access-tokens/new. For personal plans, add 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 https://openrouter.ai/keys and paste it into Settings. To show account balance and model activity, also create a management key at https://openrouter.ai/settings/provisioning-keys. Management keys cannot be used for inference; AI Gauge stores it separately and only uses it for OpenRouter management endpoints. Daily spend budget is optional.

Multiple Claude / Codex accounts

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.

Paste cookie (fallback)

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 (or https://chatgpt.com) in Chrome / Edge / Firefox as you normally do.

For ChatGPT, press F12 → Network, reload the page, click a chatgpt.com request, and copy the full Request Headers → Cookie: value. This includes split session cookies plus companion auth cookies such as __Secure-oai-is.

For Claude, press F12 → Network, reload https://claude.ai/new#settings/usage, click a claude.ai request, and copy the full Request Headers → Cookie: value. It must include sessionKey.

In the app: Settings → Claude or Settings → Codex → click Paste cookie next to the account, paste, Save.

Daily use

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.

Build a standalone binary

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 run xattr -dr com.apple.quarantine ai-gauge.app once.

Linux: no signing layer; just make ai-gauge executable if it isn't already.

See RELEASING.md for maintainer release steps.

Tests

.\.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.

Contributing

Bug reports, provider-layout fixes, and PRs are welcome. See CONTRIBUTING.md for environment setup, test commands, and the issue templates to use.

Notes / limitations

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 in src/aigauge/providers/{claude,codex}.py needs adjusting — the rest of the app keeps working.

The Copilot REST endpoint returns the current calendar month of 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

[truncated for AI cost control]