Monitor your Claude AI usage limits directly from your macOS desktop.
Website · Install · Features · Privacy · Docs · Releases
Requires a Claude Pro, Max, or Team plan. The free plan does not expose usage data.
A native menu bar app, desktop widgets, and a floating overlay that track your Claude usage in real time.
- Menu bar. Live percentages with color-coded thresholds, and a popover dashboard you compose element by element (rings, chips, arcs, pacing bars at full, half, or third width), start from built-in templates, and save as your own.
- Dashboard. A three-space window (Monitoring / History / Settings) with flippable tiles, 7-day sparklines, peak day, and a pacing-vs-equilibrium graph.
- History. Tokens over time from Claude Code's local logs: a stacked chart by model, project ranking, session counts, and cache hit rate, filterable by model family across 24h to 90d ranges.
- Widgets. Native WidgetKit gauges, progress bars, and pacing, refreshed reactively.
- Agent Watchers. A floating overlay of your live Claude Code sessions, terminals and VSCode-family extensions alike. Click a session to jump to its terminal or editor (Terminal, iTerm2, tmux, Kitty, WezTerm), right-click for quick actions.
- Smart Color. Blends how much you have used with how fast you are burning, so the color warns you before the number does. Three temperaments set how cautious it is.
- Smart pacing. Are you burning through tokens or cruising? Four zones: chill, on track, warning, hot.
- Themes. Four presets plus full custom colors, a glow or flat look, and configurable warning thresholds.
- Notifications. Per-surface and per-event toggles: escalation, recovery, pacing, scheduled reset reminders, extra credits, token expiry.
Everything in detail on the website.
Open the DMG, drag TokenEater to Applications, and launch it. The DMG is signed with a Developer ID and notarized by Apple, so Gatekeeper lets it run on first launch without any extra steps.
brew tap AThevon/tokeneater
brew trust AThevon/tokeneater
brew install --cask tokeneater
brew trustis required on Homebrew 6.0+, which no longer loads a third-party tap until you trust it.
Prerequisites: Claude Code installed and authenticated (claude then /login), on a Pro, Max, or Team plan.
- Open TokenEater: a guided setup walks you through connecting your account
- Right-click on the desktop > Edit Widgets > search "TokenEater"
TokenEater checks for updates automatically. When a new version is available, a modal lets you download and install it in-app; macOS will ask for your admin password to replace the app in /Applications.
If you installed via Homebrew: brew update && brew upgrade --cask tokeneater
Delete TokenEater.app from Applications, then optionally clean up shared data:
rm -rf /Applications/TokenEater.app
rm -rf ~/Library/Application\ Support/com.tokeneater.sharedIf you installed via Homebrew: brew uninstall --cask tokeneater. For a complete wipe, caches and widget state included, use the clean reset in the troubleshooting guide.
git clone https://github.com/AThevon/TokenEater.git
cd TokenEater
./build.shThe script checks Xcode, installs XcodeGen if needed, and assembles the app. Local builds are not notarized, so Gatekeeper blocks the first launch (right-click > Open, or System Settings > Privacy & Security > Open Anyway). The step-by-step walkthrough is in SETUP.md.
TokenEater reads the OAuth access token Claude Code already keeps in your macOS Keychain, the same token Claude Code itself uses. At first launch, macOS asks you to allow that access: click Always Allow once. The prompt is standard macOS behavior for any app reading a keychain item it did not create, and since the read goes through Apple's own security tool, whose signature never changes, the prompt does not come back on updates.
Everything the app does with the token:
GET api.anthropic.com/api/oauth/usage, your current usage statsGET api.anthropic.com/api/oauth/profile, your plan info
Both are read-only. The app cannot send messages, read conversations, or modify your account. The token never leaves your machine except for those two calls, the widget reads a local JSON file with no network or keychain access at all, and the History tab and Agent Watchers read Claude Code's local session logs without anything leaving your Mac.
Anthropic does not offer a third-party OAuth flow or scoped tokens yet, so reading the existing token is the only way an app like this can exist. If scoped tokens become available, TokenEater will adopt them immediately. The relevant code is short and auditable: keychain access in SecurityCLIReader.swift and TokenProvider.swift, the two API calls in APIClient.swift.
| Symptom | Cause | Fix |
|---|---|---|
| "Rate limited" or "API unavailable" | Your OAuth token has hit its per-token request limit | Run claude /login for a fresh token; TokenEater detects the change and recovers within seconds |
| Keychain popup on first run | A new install needs authorization to read your Claude Code token | Click Always Allow once; it sticks across updates |
| Widget stuck or not updating | macOS caches widget extensions aggressively | Remove the widget, run the clean reset, re-add the widget |
Anything deeper, including the full clean reset that wipes caches, preferences, and widget state, lives in the troubleshooting guide.
- Setup, building from source step by step
- Troubleshooting, common fixes and the clean reset
- Contributing, workflow, commit conventions, and testing
- AGENTS.md, architecture, data flow, and the SwiftUI rules, for contributors and AI agents alike
- Design system, how the windows are built and colored
Contributions are welcome: bug reports, feature ideas, and code PRs all help. Start with CONTRIBUTING.md; it covers the workflow and a few SwiftUI rules worth knowing before touching the code.
If TokenEater saves you from hitting your limits blindly, consider buying me a coffee.
MIT
Built by Adrien Thevon, software engineer in Toulouse.
Also mine:
genjutsu, creative coding skills for Claude
·
worktigre, a git worktree manager