Headroom

Know your headroom — a menu bar app that tracks Claude Code and GitHub Copilot quotas before you hit them.

Features • Install • Development • Documentation

Headroom sits in your menu bar and shows, at a glance, how much of your AI coding assistant budget you have left — across the rolling 5-hour window, the 7-day weekly cap, and the monthly Copilot allowance. It tells you when to switch from Opus to Sonnet, how long until the next reset, and projects whether you'll make it to Monday at your current pace.

It is built for developers on Claude Pro/Max and Copilot Pro/Pro+ who actually use these tools all day and have run into the "usage limit reached" wall mid-task.

Screenshots

_{The menu-bar popover — live quotas, reset countdowns, burndown projection.}

_{Onboarding  ·  Settings}

_{GitHub Copilot Business — a per-user AI-Credits quota when one is assigned  ·  org-pooled credits, where there's no per-user usage to show.}

Features

• Live quota tracking for Claude (current session, weekly all-models, weekly Sonnet, weekly Opus, optional Claude Design) and GitHub Copilot (monthly AI Credits / premium requests, with the plan and cap read live from your account). The percentages are the server-enforced numbers — read straight off the same endpoints claude.ai/settings/usage and your GitHub account use — never reconstructed by parsing local logs, so they can't drift from the quota that's actually enforced.
• Tray icon colour-coded green / amber / red from the worst quota across services; hover shows the percentage; the tray menu offers Open / Set up accounts / Settings / Quit.
• 7-day burndown — a per-quota sparkline of recent utilization plus an "On track · ~N% by reset" projection that flips to "On track to exceed · full in Xd" if you're pacing past the cap. The recent-burn-rate pace is the one figure derived from your locally-sampled history rather than the server; if that history has a gap (the app was closed for a stretch) the pace is shown muted as "rough (history gap)" rather than raising a false alarm.
• Magic sign-in for both — "Sign in with Claude" opens an embedded webview that grabs the session cookie; Copilot has "Sign in with GitHub" (OAuth device flow — enter a short code, no token to create). Each has a paste fallback under Advanced (a Claude session key, or any GitHub token). The plan and quota cap are read from your account (see SPEC.md § Auth flows).
• Multiple GitHub Copilot accounts — connect more than one GitHub account (a personal seat and a work seat, or seats in different orgs) and Headroom shows one card per account, each with its own quota and history. Add, remove, and rename accounts under Settings → GitHub Copilot accounts (the per-user API has no org name, so each is labelled by its login and renameable to the org).
• Credentials in the OS keychain — Windows Credential Manager / macOS Keychain / Secret Service on Linux. Nothing leaves your machine.
• Configurable threshold notifications — orange "heads-up" and red "critical" alerts at user-set percentages, fired once per crossing.
• One-click updates — checks GitHub for newer releases (on launch + every ~6h) and surfaces a one-time desktop alert plus an Update now banner in the popover; clicking it downloads, installs, and relaunches the new version (Windows MSI + Linux AppImage; macOS and .deb open the release page). Check on demand or toggle it off in Settings.
• Launch at login + single-instance lock — second launches surface the running tray instead of stacking icons.
• Live theme switching (auto / light / dark) and a popover that auto-fits its content above the taskbar.

Status

Stable. Both Claude and Copilot run live against the official endpoints, with credentials in the OS keychain; the burndown + sparkline + recent-burn-rate pace, threshold notifications, autostart, single-instance lock, and the click-to-expand chart all ship in the popover. Recent releases added multiple GitHub Copilot accounts (one card per account), one-click updates (download-install-relaunch from the popover), "Sign in with GitHub" for Copilot, regime-aware GitHub AI-Credits handling (after GitHub's 2026 billing migration), and per-service diagnostics. The latest version is on the Releases page; see CHANGELOG.md for full notes and FAQ.md § Scope for what's next.

Install

From a release

Grab the installer for your platform from the Releases page:

• Windows: Headroom_x.y.z_x64_en-US.msi (per-user install; registers the AppUserModelID so toast notifications correctly attribute to "Headroom").
• macOS: Headroom_x.y.z_aarch64.dmg / _x64.dmg.
• Linux: Headroom_x.y.z_amd64.AppImage or .deb.

After installing, launch from the Start Menu / Launchpad and look in your system tray (Windows 11 may hide new tray icons under the ^ overflow — drag the icon out once and it stays visible).

From source

You need Rust (1.78+) and Node.js (20+) installed.

git clone https://github.com/allandecastro/headroom.git
cd headroom
npm install
npm run tauri dev

The first launch will be slow — Cargo compiles every Rust dependency on the cold path. Subsequent launches take a few seconds.

Development

Project layout

headroom/
├── src/                    # React popover + settings UI
│   ├── components/         # TokenCard, onboarding, shared UI primitives
│   ├── lib/                # Tauri IPC wrappers, formatters, useFitWindow
│   ├── App.tsx             # Popover
│   ├── SettingsPanel.tsx   # Settings window
│   ├── OnboardingFlow.tsx  # Onboarding window
│   └── main.tsx
├── src-tauri/              # Rust backend
│   ├── src/
│   │   ├── sources/        # QuotaSource trait + claude.rs, copilot.rs
│   │   ├── commands.rs     # Tauri IPC handlers exposed to the renderer
│   │   ├── credentials.rs  # OS keychain wrapper
│   │   ├── history.rs      # Persisted per-quota usage time series
│   │   ├── notifications.rs# Threshold-crossing desktop alerts
│   │   ├── orchestrator.rs # Poll loop + classification
│   │   ├── projection.rs   # Burndown projection + recent-burn-rate pace
│   │   ├── settings.rs     # User preferences, atomic JSON persist
│   │   ├── tray.rs         # Tray icon state machine
│   │   ├── lib.rs          # AppState + run() wiring
│   │   └── main.rs
│   ├── Cargo.toml
│   └── tauri.conf.json
├── docs/                   # Mockups + screenshots used in this README
└── .github/                # Issue / PR templates + CI + release workflows

Useful commands

Tauri config notes

The popover, onboarding, and settings windows are normal decorated windows with an opaque background — vibrancy/Mica was tried and shelved (it interfered with the auto-fit-to-content sizing and made the small popover read as "ghosty" when nothing was behind it). The popover anchors to the bottom-right of the work area; settings/onboarding centre within the usable area so neither slips behind the taskbar.

The tray is built only in code (src-tauri/src/tray.rs) — tauri.conf.json must not also declare a trayIcon, or two icons appear in the system tray.

Regenerating icons

Tray icons (state-dependent, rasterized from SVG sources in assets/tray/):

python3 scripts/build_tray_icons.py

App bundle icons (from the brand mark SVG):

rsvg-convert -w 1024 -h 1024 \
  assets/headroom-app-icon.svg -o /tmp/headroom-source.png
npx tauri icon /tmp/headroom-source.png
rm /tmp/headroom-source.png

Both workflows require rsvg-convert (librsvg):

brew install librsvg

Documentation

• SPEC.md — architecture, data sources, auth flows
• DESIGN_SYSTEM.md — colors, typography, components, icons
• CHANGELOG.md — release history
• CONTRIBUTING.md — code style, PR process
• FAQ.md — common questions about setup, privacy, scope, troubleshooting
• SECURITY.md — security policy + how to report a vulnerability

Acknowledgments

Headroom exists because the data acquisition problem had already been solved by other widgets we studied:

• SlavomirDurej/claude-usage-widget — Electron implementation, embedded webview auth pattern
• rishi-banerjee1/claude-usage-widget — Swift single-file approach, Cloudflare retry logic
• bristena-op/copilot-usage-tracker — confirmed the original GitHub billing API endpoint for premium requests
• kasuken/vscode-copilot-insights — pointed us at the copilot_internal/user endpoint and its AI-Credits quota shape

Headroom's contribution is combining both services in one native menu bar app, with multiple auth paths and a cohesive design.

_{Crafted with ❤️ and AI by Allan De Castro}