LimitHUD

A menu-bar HUD that keeps a live eye on your Claude and Codex (ChatGPT) usage quotas — and warns you before you run out.

Lives in your menu bar · quiet when healthy · peek a card that forecasts when you'll run dry · with a pet that reacts to your quota · fully customizable.

• Both providers, real numbers — Claude and Codex (ChatGPT), straight from each service's own usage API (not estimates).
• Claude: 5-Hour and 7-Day windows, plus per-model weekly limits (Opus, Sonnet, hidden by default).
• Codex: 5-Hour (primary) and 7-Day (secondary/weekly) windows.
• Everything is shown as remaining (% left), not used.
• Auto-refresh every 30s / 1min / 5min, with a reset countdown per window (e.g. 2h13m, 3d20h).
• Graceful error rows per provider (not signed in / session expired / HTTP error) — never crashes, never blocks the other provider.

• Shows your tightest quota as a colored % — neutral when healthy, amber under 50%, red under 20% — so a glance tells you everything.
• Quiet when healthy: stays neutral until quota actually matters (toggleable).
• Point it at the tightest window, or lock it to Claude or Codex.
• Stays clean and text-only — the personality lives on the card.
• Left-click to peek a card, right-click for Settings… / Refresh / Quit.

• Left-click → peek: the card pops up right under the icon and auto-dismisses when you click away — popover-style, no clutter.
• 📌 Pin to keep it as a persistent floating HUD — always on top across every Space and over full-screen apps, draggable anywhere.
• Remembers where you drag it, whether peeked or pinned.

• Bottleneck hero up top: the single most-constrained window across Claude & Codex as a big %, bar, and reset countdown — your real ceiling, front and center.
• Burn-down forecast 🔥: tracks usage over time and shows "empty in ~22m at this rate" — only when running out would beat the reset, so it never cries wolf.
• A mini sparkline of recent usage, with a dashed line projecting the burn-down to empty.
• Faster-than-usual alert: it learns your typical burn rate, and when you're spending abnormally fast the forecast flips to a bold "🔥 burning ~2× your usual pace".
• Below: every window as a semantic bar (green > 50%, amber 20–50%, red < 20%) with % left and reset countdown.
• Quiet deep-dark design — real frosted glass, hairline border, monospaced uppercase labels.
• Resizable (size slider), custom background / text / bar colors — text stays readable on any color.
• Refill celebration: when a window resets, the bar sweeps back, the number rolls up, and the pet throws a little party.
• SYNCED HH:mm timestamp, refreshed each minute. Close via ✕, the menu-bar icon, or the global hotkey.

• A little illustrated, animated animal lives on the card — pick Mochi · Lota · Bao · Mozart in Settings.
• Its mood tracks your tightest window: calm and content when you've got room, more subdued as it tightens, dozing when a window is spent, and a happy little celebration on a refill.
• Mostly it just rests quietly — the occasional stretch or look-around — a calm companion, not a distraction.
• Each character speaks in its own voice in the card's title line.

• Low-quota alert — a system notification when any window drops below your threshold (default 20%).
• Recovery reminder — a notification when a window resets back above the threshold.
• Forecast alert 🔥 — a heads-up when a window is projected to run dry before it resets (within ~30 min).
• Pace alert ⚡ — a heads-up when you're burning ~2× your usual rate and under 50% left — catch a runaway session early.
• Edge-detected + cooled down, so they fire once per episode (no spam).
• System notification + sound toggles, plus quiet hours to mute reminders during a daily window.

• Reminders — alert on/off, threshold %, recovery reminder, forecast alert, pace alert, notifications, sound, quiet hours.
• Pet — choose your character: Mochi / Lota / Bao / Mozart.
• Menu bar — point at the tightest window or lock to Claude / Codex; quiet-when-healthy toggle.
• Sources — Claude / Codex toggles.
• Browser — read Claude and Codex from different browsers / profiles (great when they're under different Google accounts).
• Card content — per-window toggles to choose exactly what shows.
• Refresh — 30s / 1min / 5min.
• Card — custom global hotkey, size, custom background, text & bar color, remember position, launch at login, opacity.

LimitHUD reads your browser's session cookies locally to call each service's own usage endpoint. Reading cookies is a sensitive thing for an app to do, so here is exactly what happens:

• Cookies are decrypted on-device (the browser's SQLite store + the encryption key from your login Keychain) and used only as the Cookie header to claude.ai / chatgpt.com.
• Those are the only two hosts it ever talks to — easy to verify with Little Snitch / Proxyman, or by grepping the source for URLs.
• Decrypted cookie values live in memory only — never persisted, never logged.
• No servers, no analytics, no telemetry, no auto-updater phoning home. Updates come from Homebrew / GitHub Releases, on your initiative.
• The whole thing is open source — audit it.
• On first run macOS asks once for Keychain access (to read the browser's key) and once for notifications. Click Allow.

• macOS 13+
• Signed into claude.ai and/or chatgpt.com in a supported browser — Chrome, Brave, Edge, Arc, Vivaldi, Chromium, or Opera
• A Swift toolchain to build (Xcode or Command Line Tools — full Xcode not required)

brew install --no-quarantine zetagao/tap/limithud

Upgrade later with brew upgrade --cask limithud.

--no-quarantine skips the one-time Gatekeeper warning for this signed-but-not-notarized app. Omit it if you'd rather approve the app yourself in System Settings → Privacy & Security → Open Anyway.

1. Download LimitHUD.zip from the latest release.
2. Unzip and drag LimitHUD.app into your Applications folder.
3. First launch — the app is signed by an independent developer (not via the App Store), so macOS blocks it once:
   • Double-click it. When macOS says it can't verify the developer, open System Settings → Privacy & Security, scroll to the bottom, and click Open Anyway, then confirm. (On older macOS you can instead Control-click the app → Open.)
4. Click Allow when macOS asks for Keychain access (to read the browser's cookie key) and for Notifications.
5. Make sure you're signed into claude.ai / chatgpt.com in a supported browser (Chrome, Brave, Edge, Arc, Vivaldi, Chromium, or Opera).

The app is open source and code-signed, but not Apple-notarized — that one-time warning is expected. Prefer to audit and build it yourself? See below.

./setup-signing.sh    # once: create a stable self-signed code-signing cert
./build.sh            # compile + sign  →  LimitHUD.app
./build.sh run        # build and launch
./build.sh install    # build, install to /Applications, launch
./build.sh release v2.2   # build + zip + publish to a GitHub release (omit tag to re-upload latest)

The self-signed cert keeps the app's code identity stable across rebuilds, so the Keychain "Always Allow" sticks.

To regenerate the app icon:

swift tools/icongen.swift AppIcon.iconset && iconutil -c icns AppIcon.iconset -o AppIcon.icns

• Swift + SwiftUI + AppKit, built with Swift Package Manager — no Xcode project needed (build.sh assembles the .app by hand).
• The card is a borderless, non-activating NSPanel at .statusBar level hosting a SwiftUI view.
• Chrome cookie decryption: read the Cookies SQLite DB → fetch the Chrome Safe Storage key from the Keychain → PBKDF2-SHA1 (salt saltysalt, 1003 rounds) → AES-128-CBC (handling the 32-byte domain-hash prefix on Chrome ≥ v24). A small system module (CBridge) bridges sqlite3 + CommonCrypto.

MIT — see LICENSE.

brew install --no-quarantine zetagao/tap/limithud

./setup-signing.sh    # 首次：创建稳定自签名证书
./build.sh            # 编译 + 签名 → LimitHUD.app
./build.sh run        # 编译并启动
./build.sh install    # 编译 + 装到 /Applications 并启动