Windows 11 system-tray app that shows remaining AI coding usage for Cursor, ChatGPT Codex, Claude, Gemini, Devin, and MiniMax — with an optional always-on-top overlay.
Built with Tauri 2 + React.
- System tray icon with flyout panel
- Optional floating overlay (enabled providers only)
- Auto-detect Cursor login (
%APPDATA%\Cursor\...\state.vscdb) - Auto-detect Codex login (
%USERPROFILE%\.codex\auth.json) - Auto-detect Devin desktop login (
%APPDATA%\Devin\...\state.vscdb) or CLIcredentials.toml - Optional Claude Code login (
%USERPROFILE%\.claude\.credentials.json) — off by default - Optional Gemini CLI OAuth (
%USERPROFILE%\.gemini\oauth_creds.json) — off by default - Optional Devin session / team service key overrides in Settings
- Optional MiniMax Token Plan usage via API key (
platform.minimax.io→ console → plan) — off by default - Threshold toasts at 80% / 95% used
- Notify when usage windows reset (Claude 5-hour, Devin daily, Cursor monthly, …) — including resets that happened while HeadRoom was closed
- Modular provider plugin design (registry-only registration)
- Single-instance portable EXE
See CHANGELOG.md for the full release history.
All credentials stay on your machine under %APPDATA%\headroom\. HeadRoom only calls the same provider backends you already use. No HeadRoom cloud sync.
See SECURITY.md for reporting and storage details.
Provider personal usage endpoints are unofficial and may change, rate-limit, or break. Use at your own risk and respect each provider’s terms of service. Failures show per-provider errors without crashing the app.
- Windows 11
- Node.js 20+ (for development)
- Rust stable (for development)
- Microsoft C++ Build Tools (MSVC) for Tauri on Windows
- WebView2 (included with Windows 11)
npm install
npm run tauri:devLeft-click the tray icon to open the flyout. Right-click for Refresh / Toggle overlay / Quit.
npm run build:portableOutput: portable/HeadRoom.exe (~15 MB)
That file is a single portable binary (UI assets are embedded). Copy it anywhere and run it.
Only one instance runs at a time. Launching the exe again shows the top status bar instead of starting a second process.
Requirement: WebView2 Runtime (ships with Windows 11). Settings/secrets still live under %APPDATA%\headroom\ — the exe is portable; config is per-user.
Build note: Rust artifacts go to %LOCALAPPDATA%\headroom-cargo-target by default so Dropbox/synced folders do not lock target/ mid-compile. Override with CARGO_TARGET_DIR if needed.
Installer build (optional): npm run tauri:build
Releases are automated with GitHub Actions.
- Ensure
mainis clean and up to date. - Cut a release:
npm run release -- patch # 0.1.0 → 0.1.1
npm run release -- minor # 0.1.0 → 0.2.0
npm run release -- major # 0.1.0 → 1.0.0
npm run release -- 0.2.0 # exact versionThat bumps versions in package.json, src-tauri/Cargo.toml, and src-tauri/tauri.conf.json, commits, tags vX.Y.Z, and pushes. The Release workflow then:
- builds the Windows portable
HeadRoom.exe - builds the NSIS installer
- publishes a GitHub Release with generated notes + artifacts
CI builds on every push/PR to main (CI).
Architecture is registry-based (open-closed):
- Add
src/providers/<id>/index.tsexporting aProviderPlugin(id, displayName, accentColor,enabledByDefault, auth capability). - Register it in
src/providers/registry.ts— the only place that lists concrete plugins. - Add
src-tauri/src/providers/<id>.rsthat returns aUsageSnapshot, and a match arm insrc-tauri/src/providers/mod.rs. - Settings UI already renders credential fields from
auth; flyout/overlay/alerts need no changes (disabled providers are hidden).
Do not add switch (provider) in Flyout, Overlay, or alert code.
| File | Purpose |
|---|---|
%APPDATA%\headroom\settings.json |
Enabled providers, overlay, poll interval, notifications |
%APPDATA%\headroom\secrets.json |
Optional pasted tokens / keys (local only) |
%APPDATA%\headroom\last_resets.json |
Last-seen window reset timestamps (dedupes "limits reset" notifications across restarts) |
MIT — see LICENSE.