Skip to content

About

Windows desktop widget showing live quota for locally installed AI coding tools

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

328 Commits

Folders and files

Repository files navigation

nayots

AI Usage Monitor

See how much of your AI coding plan you have left β€” without opening a session to ask. πŸ“Š

A small Windows desktop widget that shows live quota usage for the AI coding tools already installed on your machine: Claude Code, Codex and Cursor. It sits in your notification area, and one glance tells you where you stand.

Latest release Licence: MIT Windows 11 x64 No telemetry

The widget: a card for Claude Code showing 5 hour and 7 day quota windows, a card for Codex showing its own window, and a card for Cursor showing a monthly spend window reading $11.71 of $100 - each with a usage bar and a countdown to reset.

πŸ“¦ The repository is called ai-agent-usage-monitor; the app calls itself AI Usage Monitor. Same thing.


πŸš€ Quickstart

Three steps, about a minute. No installer, no admin rights, no setup wizard.

1. Download ⬇️ β€” grab AiUsageMonitor-v<version>-win-x64.exe from the latest release.

2. Run it ▢️ β€” double-click. Because the file isn't code-signed, Windows shows "Windows protected your PC" the first time: click More info β†’ Run anyway. If you'd rather check the download before trusting it, here's what the warning means and how to verify the file ↓

3. That's it βœ… β€” the widget appears with a card per provider, and an icon lands in your notification area. Press Ctrl+Alt+Q any time to bring it back.

That one file carries its own .NET runtime, so there is nothing else to install. πŸŽ’

🚫 My network blocks .exe downloads

Take AiUsageMonitor-v<version>-win-x64.zip from the same release instead β€” it holds the identical executable plus its checksum file, built in the same release run. Extract both and carry on.

If your filter also inspects inside archives, it will block this too. That's the filter doing its job, and the answer is your IT department, not a workaround. πŸ™‚


πŸ”’ Is it safe?

You're about to run an unsigned executable that reads an OAuth token off your disk, so the honest answer isn't "trust me" β€” it's here is exactly what it does, and here is where to check. Every claim below points at the file that implements it.

🌐 Everything that leaves your machine

Four requests. That's the whole list.

Request Goes to Carries
πŸ“ˆ Your Claude Code quota api.anthropic.com β€” Anthropic's own server The OAuth token Claude Code already stored, over TLS
πŸ“ˆ Your Codex quota Codex's own app-server, launched on your machine Nothing from this app. Codex then asks OpenAI for your limits itself, exactly as it does in a normal session
πŸ“ˆ Your Cursor spend api2.cursor.sh β€” Cursor's own server The access token Cursor already stored, over TLS
πŸ”” Update check, once a day api.github.com Nothing about you. No version, no identifier, no machine information, no token

Every HTTP request this app makes lives in exactly three files β€” ClaudeOAuthUsageProbe.cs, CursorUsageProbe.cs and GitHubReleaseClient.cs. There are no others, and you can read all three in a few minutes.

The Codex path makes no HTTP request at all: it launches the codex executable already on your machine and asks it one question over a pipe (CodexProbe.cs). Codex answers that question by contacting OpenAI on its own β€” the same thing it does when you use it β€” which is why the numbers are live rather than cached. This app never reads Codex's credentials or session files. 🀝

The only other thing the app can open is your browser, at one of two GitHub URLs compiled into the program. Never a URL that arrived over the network.

πŸ”” About the update check

It's an unauthenticated GET of GitHub's public release listing β€” the same page anyone can open in a browser. Its User-Agent is the constant string AiUsageMonitor, deliberately carrying no version, and there's no query string, no identifier and no token. It runs once every 24 hours (retrying an hour later if it failed), and sends back the release feed's ETag so GitHub can answer "nothing changed" without resending anything. As with any HTTPS request, GitHub sees the connection came from your IP β€” that's how the internet works, not something this app adds.

The comparison happens on your computer. Switch it off in Settings β†’ Updates and no unattended request is ever made; the Check now button still works when you press it. The app never downloads or installs anything either β€” when a new version exists, it offers to open the release page in your browser. 🧭

πŸ’Έ It only ever reads

The monitor asks for numbers and nothing else. Cursor's local database is opened read-only; the app cannot write to it even by accident. It never sends a prompt, starts a model turn, calls a generation endpoint, buys credits or changes your subscription β€” it cannot cost you anything, and it does not consume the quota it displays.

If a provider isn't installed, it gets no card at all (you can turn Show providers that are not installed back on in Settings). If a request fails, the card shows a visible error and the scheduler backs off. It never invents a number, reuses a stale one, or shows a zero to fill the gap. If you see a number, a provider returned it.

πŸ™… What it never does

  • ❌ No telemetry, analytics or crash reports β€” nothing is ever sent to the author
  • ❌ No website scraping, no browser automation, no access to browser cookies or profiles
  • ❌ No HTTP client follows redirects, and every destination is hardcoded β€” a response can't send the app somewhere else
  • ❌ Never writes, refreshes, rotates or modifies your credentials β€” token lifecycle stays your provider's job
  • ❌ Never writes to any provider's own configuration files or local databases
  • ❌ No administrator rights, no service, no driver, no scheduled task
  • ❌ No quota history, no database, no account to create, no sign-in

πŸ”΅ About Cursor's token, and its database

Cursor keeps its sign-in in a SQLite database β€” %APPDATA%\Cursor\User\globalStorage\state.vscdb, the same file VS Code-based editors use for local state. The app opens that file read-only and never writes to it, reads exactly three things from it β€” the access token, your plan type, and your team id β€” and asks Cursor's own server what you have spent this billing cycle.

It deliberately does not read the email address or profile stored two rows away, and it never calls Cursor's team-roster endpoints, which would hand back your colleagues' names and work email addresses to compute a single percentage. Your team id is used as a request parameter and appears nowhere else β€” not on screen, not in a log, not in a diagnostic dump. πŸ”

πŸ”‘ About that Claude Code token

It's read from %USERPROFILE%\.claude\.credentials.json β€” the file Claude Code itself already wrote β€” and used as the bearer token for exactly one HTTPS request to Anthropic. It's never kept in a field, cached, written anywhere, logged, shown on screen, copied to the clipboard, or included in any diagnostic output. That request doesn't follow redirects, so nothing can carry the token to a different host. πŸ”

πŸ“ Where it puts things

Path Contents
%APPDATA%\AiUsageMonitor\settings.json Your settings. Plain JSON, hand-editable.
%LOCALAPPDATA%\AiUsageMonitor\logs Rolling log of the app's own events, 1 MB Γ— 5 files.
HKCU\...\Run One entry, and only if you switch on Start with Windows.

Nothing is written machine-wide. To uninstall: switch off Start with Windows, delete the .exe, delete those two folders. Done β€” there's nothing else of ours on your PC. 🧹

Windows will warn you, and here is why

The executable is not code-signed, so SmartScreen shows "Windows protected your PC" on first run. This is identical whether you downloaded the .exe or extracted it from the .zip β€” Windows carries the download mark through extraction, so the zip is not a way around the warning.

A signing certificate costs money every year and requires a verified publisher identity this project doesn't have. That's a real limitation, not one to wave away. What every release does publish is a SHA256 beside the binary, and checking it takes ten seconds:

Get-FileHash .\AiUsageMonitor-v<version>-win-x64.exe -Algorithm SHA256

Compare that against the matching .sha256 file β€” on the release page if you downloaded the .exe, or the copy extracted from the .zip. If they differ, don't run it. ⚠️

Being straight about what that proves: a match means your copy is byte-for-byte the file that release published. It does not prove who published it β€” that's the job a signature would do. If you want more assurance than a hash, the source and the workflow that builds every release are both right here, and you can build it yourself.

πŸ›‘οΈ Found a way to break any of the above? See SECURITY.md and report it privately β€” never as a public issue.


πŸ”Œ Providers

Provider What it reads Tier Verified against
🟒 Codex codex app-server over stdio, JSON-RPC account/rateLimits/read βœ… Official codex-cli 0.144.6
🟣 Claude Code Anthropic's own usage endpoint, authenticated with the OAuth token Claude Code already stored on this machine ⚠️ Unofficial Claude Code 2.1.226
πŸ”΅ Cursor Cursor's own dashboard API, authenticated with the access token Cursor already stored on this machine ⚠️ Unofficial Cursor 3.16.29

⚠️ The Claude Code and Cursor mechanisms are undocumented and may stop working without notice. Neither is a published API and neither carries a stability guarantee. The app labels both Unofficial everywhere they appear, and when one breaks its card goes to a plain error state rather than showing you something comforting and wrong.

Cursor's card shows your spend against your monthly ceiling β€” that is the limit Cursor actually enforces β€” on the same percentage bar as every other provider, with the money itself ($11.71 of $100) written underneath. A percentage tells you where you are; the amount tells you what is left.

You don't need all three. A provider that isn't installed is simply left out and costs nothing. 🀷 Claude Code signed in with an Anthropic Console account or API key has no subscription quota, so its card shows today's and this month's tokens with an estimated cost instead (β‰ˆ $38.20 Β· 12.4M tokens), totalled from Claude Code's own transcripts on this PC and priced at Anthropic's published list prices. It is labelled an estimate because it is one: it knows nothing of negotiated discounts, and nothing of usage from other machines.


πŸ–₯️ Using it

  • πŸƒ Cards β€” one per provider: name, version, mechanism tier, connection state, and a bar per quota window with its usage and a countdown to reset. Where a window's real limit is money rather than a percentage, the amount is written beneath its bar.
  • πŸ“‰ Pace projection β€” when a window is burning faster than its clock, the row says how early it will run out at that rate. It stays quiet until a tenth of the window has elapsed, and speaks only when the projection lands meaningfully before the reset rather than on a few minutes' drift. Switch it off in Appearance.
  • ❎ Closing hides it. The close button, Alt+F4 and the system menu all hide the widget to the notification area. Only Exit in the tray menu ends the process.
  • πŸ“ The tray icon is a live readout β€” a miniature of the bars, redrawn as the state changes, coloured to stay legible against your taskbar rather than against the app's theme.
  • ⌨️ Ctrl+Alt+Q brings the widget back from anywhere. If another application already owns that shortcut, Settings says so instead of failing quietly. Can be switched off.
  • πŸ“Œ Pin keeps it above other windows; unpinned, it hides when you click away.
  • 🀏 Compact tightens everything; Mini shrinks it to a docked strip.
  • πŸ”” Notifications fire as you cross usage milestones, and when a provider fails or recovers. An alert never says why something failed β€” that stays on the card.

βš™οΈ Settings

Everything applies immediately. There is no OK, no Apply, no restart. ⚑

🎨 Appearance Theme (System / Light / Dark β€” Windows High Contrast is detected and always wins), density, colour bars by usage, pace projection
πŸͺŸ Window Always on top, mini mode and its dock edge, global hotkey, start with Windows, reset window position
πŸ”Œ Providers Order, visibility, and a per-provider refresh interval
πŸ”„ Refresh Refresh interval (default 2 min) and the age at which data is called stale (default 5 min)
πŸ”” Notifications On or off, which usage thresholds alert, and quiet hours
🩺 Diagnostics Everything the app knows about each provider, plus a redacted copy button

⏱️ The refresh interval will not go below 120 seconds, globally or per provider. Asking a provider for your quota far more often than it actually changes is how an app gets throttled β€” and a throttled provider tells you less, not more. A hand-edited smaller value in settings.json is read as 120 and left alone in the file.


🩺 Something's wrong?

Settings β†’ Diagnostics β†’ Copy puts a plain-text report on your clipboard: what each provider reported, when, how long it took, what's scheduled next, and why.

Before it's copied, your user folder is replaced with %USERPROFILE% and your Windows user name with %USERNAME% (when that name is three characters or longer β€” replacing a one- or two-letter name would shred the rest of the report). No credential is read into that screen at all, so none can leak through it. It's plain text, so give it a read before you paste it anywhere. 🧼

Please include that report when opening an issue. πŸ™


🚧 Limitations

Worth knowing before you download:

  • πŸͺŸ Windows only. WPF and Windows-specific APIs throughout; there is no macOS or Linux build.
  • πŸ’» x64. It runs under emulation on Windows on ARM; there's no native ARM64 build.
  • πŸ•°οΈ No history. Every value is instantaneous. Your numbers are never recorded, charted or kept between runs.
  • ⚠️ The Claude Code and Cursor mechanisms are unofficial and can break whenever either endpoint changes.
  • 🧩 Quota windows are whatever the provider reports. Their number, names and durations are discovered at runtime, not hardcoded β€” so a provider adding a new window shows up without an app update, and one whose name the app doesn't recognise is displayed with the provider's own raw label rather than a guess.
  • ⏳ Reset times appear only where the provider reports them. A window's length is worked out from its own name where that is unambiguous (five_hour β†’ 5 hours) and left off where it isn't β€” never invented.
  • πŸ§ͺ Pre-1.0. It works, it's used daily, and the version number stays honest about depending on an unofficial endpoint.

πŸ› οΈ Building from source

Requires the .NET 10 SDK (the feature band is pinned in global.json).

dotnet build                                   # warnings are errors
dotnet test                                    # domain, infrastructure and app suites
dotnet run --project src/AiUsageMonitor.Poc    # live probe: does the real provider reads described above
powershell -File build/publish.ps1             # the single-file release artifact

build/publish.ps1 produces the self-contained executable and stages it with its checksum under artifacts/. The release artifact is always the self-contained build β€” the framework-dependent one is a few hundred kilobytes, runs fine on a machine that already has the .NET 10 Desktop Runtime, and fails everywhere else.

πŸ““ Provider capability findings is the verification record behind the provider table above: how each mechanism was proven, the wire formats and schemas observed, the version behaviour, and the mechanisms that were investigated and rejected for carrying no usable quota signal.


πŸ“„ Licence

MIT. Use it, fork it, ship it.


Built by nayots. πŸͺΆ

About

Windows desktop widget showing live quota for locally installed AI coding tools

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages