TokenEater

Monitor your Claude AI usage limits directly from your macOS desktop.
Website · Docs · Download

Requires a Claude Pro, Max, or Team plan. The free plan does not expose usage data.

What is TokenEater?

A native macOS menu bar app + desktop widgets + floating overlay that tracks your Claude AI usage in real-time.

• Menu bar — Live percentages, color-coded thresholds, detailed popover dashboard
• Widgets — Native WidgetKit widgets (usage gauges, progress bars, pacing) with reactive refresh
• Agent Watchers — Floating overlay showing active Claude Code sessions with dock-like hover effect. Click to jump to the right terminal (Terminal.app, iTerm2, tmux, Kitty, WezTerm).
• Smart pacing — Are you burning through tokens or cruising? Three zones: chill, on track, hot.
• Themes — 4 presets + full custom colors. Configurable warning/critical thresholds.
• Notifications — Alerts at warning, critical, and reset.

See all features in detail on the website.

Install

Download DMG (recommended)

Download TokenEater.dmg

Open the DMG, drag TokenEater to Applications, then:

1. Double-click TokenEater in Applications — macOS will block it
2. Open System Settings → Privacy & Security — scroll down to find the message about TokenEater
3. Click Open Anyway and confirm

Important: Do not use xattr -cr to bypass this step — it prevents macOS from approving the widget extension, which will then be flagged as malware in the widget gallery.

Homebrew

brew tap AThevon/tokeneater
brew install --cask tokeneater

First Setup

Prerequisites: Claude Code installed and authenticated (claude then /login). Requires a Pro, Max, or Team plan.

1. Open TokenEater — a guided setup walks you through connecting your account
2. Right-click on desktop > Edit Widgets > search "TokenEater"

Update

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

Uninstall

Delete TokenEater.app from Applications, then optionally clean up shared data:

rm -rf /Applications/TokenEater.app
rm -rf ~/Library/Application\ Support/com.tokeneater.shared

If installed via Homebrew: brew uninstall --cask tokeneater

Build from source

# Requirements: macOS 14+, Xcode 16.4+, XcodeGen (brew install xcodegen)

git clone https://github.com/AThevon/TokenEater.git
cd TokenEater
xcodegen generate
plutil -insert NSExtension -json '{"NSExtensionPointIdentifier":"com.apple.widgetkit-extension"}' \
  TokenEaterWidget/Info.plist 2>/dev/null || true
xcodebuild -project TokenEater.xcodeproj -scheme TokenEaterApp \
  -configuration Release -derivedDataPath build build
cp -R "build/Build/Products/Release/TokenEater.app" /Applications/
# Then approve via System Settings → Privacy & Security → Open Anyway

Architecture

TokenEaterApp/           App host (settings, OAuth, menu bar, overlay)
TokenEaterWidget/        Widget Extension (WidgetKit, reactive refresh)
Shared/                  Shared code (services, stores, models, pacing)
  ├── Models/            Pure Codable structs
  ├── Services/          Protocol-based I/O (API, TokenProvider, SharedFile, Notification, SessionMonitor)
  ├── Repositories/      Orchestration (UsageRepository)
  ├── Stores/            ObservableObject state containers
  └── Helpers/           Pure functions (PacingCalculator, MenuBarRenderer, JSONLParser)

The app reads Claude Code's OAuth token silently from the macOS Keychain (kSecUseAuthenticationUISkip), calls the Anthropic usage API, and writes results to a shared JSON file. A TokenFileMonitor watches for credential changes via FSEvents and triggers immediate refresh. The widget reads the shared file — it never touches the network or Keychain. The Agent Watchers overlay scans running Claude Code processes every 2s using macOS system APIs and tail-reads their JSONL logs.

How it works

GET https://api.anthropic.com/api/oauth/usage
Authorization: Bearer <token>
anthropic-beta: oauth-2025-04-20

Returns utilization (0–100) and resets_at for each limit bucket.

Security & Privacy

TokenEater reads an OAuth access token from the Claude Code keychain entry — the same standard token that Claude Code itself uses. At first launch, macOS will prompt you to allow this access; this is normal macOS behavior for any app reading a keychain item it didn't create.

What the app does with the token:

• Calls GET /api/oauth/usage (your current usage stats)
• Calls GET /api/oauth/profile (your plan info)

What the app cannot do: send messages, read conversations, modify your account, or access anything beyond read-only usage data.

The token never leaves your machine except for these two API calls to api.anthropic.com. The widget reads a local JSON file and has no network or keychain access at all.

Anthropic does not currently offer a third-party OAuth flow or scoped API tokens — reading the existing token from the keychain is the only option. If scoped tokens become available, TokenEater will adopt them immediately. The entire codebase is open source and auditable: keychain access is in KeychainService.swift, API calls in APIClient.swift.

Support

If TokenEater saves you from hitting your limits blindly, consider buying me a coffee ☕

License

MIT