Your AI coding quota, one glance away.
TokenGauge lives in your Mac’s menu bar and shows how much Claude Code or Codex quota you have left. Check reset times, browse weekly and yearly activity, and keep a private local history without opening a terminal.
App views rendered with synthetic demonstration data.
Classic panels, yearly history, and Settings
- Three views: Codex, Claude, or Unified. Individual views show only that provider; Unified puts both quota cards side by side.
- Flexible layouts: keep the classic panel, choose compact rows, or use separate quota rings. Switch from the panel header or Settings → Appearance.
- A readable menu bar: independently choose percentages, mini bars, or mini rings, with Large, Medium, or Small sizing. Exact percentages remain available on hover and in the panel.
- Quiet by design: optional brief transitions respect Reduce Motion; menu indicators redraw only when their data or appearance changes.
- Separate limits: general weekly quota and additional provider windows stay separate. Hide Luna weekly reserve in Settings if you do not use it.
- Browsable activity: rolling seven days, Monday-based weeks with previous/next navigation, or a yearly calendar that always shows Codex and Claude together, whichever view you are in. Five intensity levels show how much you used that day, colored by the provider with more recorded tokens. Hold the pointer over a day or click it to pin a card with per-provider tokens, percentages, model detail, and your current and best streaks; Esc, a click outside, scrolling, or changing view closes it. Separate month blocks and highlighted weekend rows make the year easier to scan.
- Local history: SQLite preserves daily totals and observed model/reasoning effort metadata after provider logs are trimmed. Missing days remain distinct from recorded zero usage.
- Hourly quota pace: an optional estimate in percentage points per hour for each weekly limit, based on verified recent readings, with a short explanation and dated last-active measurement.
- English and Spanish: follows your system language initially, with an explicit language choice in Settings.
- Native updates: daily checks, an in-panel banner with download progress, and manual checks in About.
- No telemetry, ads, or model requests.
Requires macOS 14 or later and an Apple Silicon Mac. Intel builds are not currently distributed.
- Download the DMG from Releases.
- Drag TokenGauge to Applications and open it. The app appears in the menu bar.
- Install and sign in to Codex CLI or Claude Code with the subscription you use. You do not need both.
- Select your provider in TokenGauge. It refreshes automatically; use the header refresh button to check immediately.
If Codex was installed using a custom npm prefix, nvm, asdf, or Volta and is not detected, use Settings → Detection options → Choose Codex executable… to select the executable you use in Terminal. Automatic detection can be restored from the same row.
TokenGauge is a usage viewer, not a replacement for either provider. On a Mac without a signed-in provider, it shows an unavailable/sign-in state and keeps the setup links accessible in Settings. It never invents a balance or asks for an API key.
Permissions: no Accessibility, Automation, Screen Recording, or Full Disk Access is needed. Launch at login is optional. Claude quota requires reading Claude Code’s existing OAuth credential from the macOS Keychain; macOS may request access depending on that item’s access policy. TokenGauge never creates, directly renews, rotates, or exports the credential. Optional automatic reconnection briefly starts Claude Code in safe mode without a prompt so Claude Code can renew its own expired session. This requires one-time consent, can be disabled in Settings, and uses bounded retries. Missing or revoked access still requires signing in through Claude Code. During temporary failures, last-known limits remain explicitly marked as historical.
Release builds check for updates daily. When one is available, a banner appears in the panel with download and extraction progress, then offers Install now or Later. Installing relaunches the app. If you choose Later, an Install button stays in the panel and in About TokenGauge until you use it, including after restarting the app. Automatic checking can be disabled in Settings; a manual check is available in About whenever no update is in progress. There are no separate Sparkle update windows.
Updates use Sparkle, a signed ZIP, and an EdDSA-signed appcast on GitHub Releases. Development builds stay off the public update channel.
The menu bar shows the selected provider’s current balance. Codex uses its general quota; a separate Luna reserve is displayed independently and is never added to it. Claude uses its tightest scoped weekly limit, falling back to the general weekly limit. Token activity totals are not quota percentages. The current Codex account protocol supplies daily tokens, not daily turn counts; the chart labels its unit explicitly. Provider windows and account availability depend on your plan and may change upstream.
Hourly pace uses at least three verified samples spanning 30 minutes in the last hour. It restarts after quota resets, decreases, or long observation gaps. The info button explains the estimate and shows dated recent and previous measurements. During inactivity or after reopening the app, the last active pace remains explicitly labeled as historical until a new valid measurement with consumption is available. Pace observations, including idle readings, are stored locally without expiry for future daily comparisons. For example, 5 pp/h means an estimated five percentage points of that weekly allowance per hour. Model/effort token totals describe locally observed activity; they do not allocate quota percentages to Medium, High, XHigh, or other efforts. Daily totals use the largest observed provider or local total, without adding overlapping sources. Local effort detail is collected from the last seven days and retained thereafter; unavailable older detail cannot be reconstructed.
If a live read fails, historical balances are not presented as current quota. Authentication required, denied access, stale data, and a locally marked cancelled subscription remain distinct. Cancellation is not inferred from inactivity or a lost session. Each provider has an independent manual cancellation switch in Settings. It preserves local history and your selected view; it does not cancel billing. Tracking resumes only after live access and newly observed activity are confirmed.
Codex metrics come from the local codex app-server account methods. Claude quota comes from its read-only usage endpoint, using the existing credential only in memory. This integration depends on provider behavior and is not an official provider product.
Local activity scans decode timestamps, message IDs, model identifiers, reasoning effort, and numeric counters. Prompt and response fields are not decoded, logged, or persisted. Only normalized metrics and aggregate history are saved under ~/Library/Application Support/TokenGauge, with user-only permissions. No usage is sent to a TokenGauge server. Provider quota requests contact the provider, and update checks contact GitHub.
See SECURITY.md for reporting and update-channel details.
Use Xcode/Swift 6.2 or newer on macOS. No Node, Homebrew runtime, or web service is required.
make ci-check
make install-devThe development installer requires an Apple Development signing identity and installs to ~/Applications/TokenGauge.app. It does not modify Claude Code’s configuration. To stage a local bundle without installing, use make stage.
The optional scripts/install_claude_statusline.sh supports an existing shell status-line script containing input=$(cat). It adds a normalized quota capture fallback and creates a backup; it is not needed for normal live quota reads. It refuses unsupported scripts instead of overwriting a custom setup. Do not replace someone’s status-line configuration merely to enable the fallback.
Release guide · Contributing · Changelog
Created by StevenACZ. Also see SapoWhisper, Encaje, and MacGauge.
TokenGauge is independently developed and is not affiliated with OpenAI or Anthropic. Provider names and marks belong to their respective owners. Source code is MIT licensed; Sparkle notices are included in docs/licenses.