by AThevon
Native macOS app to monitor Claude AI usage limits and watch your coding sessions live
# Add to your Claude Code skills
git clone https://github.com/AThevon/TokenEaterLast scanned: 5/30/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-30T14:59:56.085Z",
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
Requires a Claude Pro, Max, or Team plan. The free plan does not expose usage data.
A native macOS menu bar app + desktop widgets + floating overlay that tracks your Claude AI usage in real-time.
See all features 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 install --cask tokeneater
Prerequisites: Claude Code installed and authenticated (claude then /login). Requires a Pro, Max, or Team plan.
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.shared
If installed via Homebrew: brew uninstall --cask tokeneater
# 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/
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, SessionHistory)
├── Repositories/ Orchestration (UsageRepository)
├── Stores/ ObservableObject state containers (Usage, Theme, Settings, History, MonitoringInsights, Session, Update)
└── Helpers/ Pure functions (PacingCalculator, MenuBarRenderer, JSONLParser, SmartColor)
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.
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.
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:
GET /api/oauth/usage (your current usage stats)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 SecurityCLIReader.swift (primary) and KeychainService.swift (fallback), 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 in your terminal for a fresh token - TokenEater detects the change and recovers automatically within seconds |
| Keychain popup asking to access "Claude Code-credentials" | First run on a new install needs to authorize /usr/bin/security to read your Claude Code token | Click Always Allow once - it sticks across future app updates |
| Widget stuck / not updating | macOS caches widget extensions aggressively | Remove the widget, run a clean reset, re-add the widget |
If something is broken and you want to start fresh, run this in your terminal. It kills all related processes, wipes caches, preferences, and containers, then removes the app:
# 1. Kill processes
killall TokenEater NotificationCenter chronod cfprefsd 2>/dev/null; sleep 1
# 2. Wipe preferences
defaults delete com.tokeneater.app 2>/dev/null
defaults delete com.claudeusagewidget.app 2>/dev/null
rm -f ~/Library/Preferences/com.tokeneater.app.plist
rm -f ~/Library/Preferences/com.claudeusagewidget.app.plist
# 3. Wipe sandbox containers
for c in com.tokeneater.app com.tokeneater.app.widget com.claudeusagewidget.app com.claudeusagewidget.app.widget; do
d="$HOME/Library/Containers/$c/Data"
[ -d "$d" ] && rm -rf "$d/Library/Preferences/"* "$d/Library/Caches/"* "$d/Library/Application Support/"* "$d/tmp/"* 2>/dev/null
done
# 4. Wipe shared data and caches
rm -rf ~/Library/Application\ Support/com.tokeneater.shared
rm -rf ~/Library/Application\ Support/com.claudeusagewidget.shared
rm -rf ~/Library/Caches/com.tokeneater.app
rm -rf ~/Library/Group\ Containers/group.com.claudeusagewidget.shared
# 5. Wipe WidgetKit caches (critical - macOS keeps old widget binaries here)
TMPBASE=$(getconf DARWIN_USER_TEMP_DIR)
CACHEBASE=$(getconf DARWIN_USER_CACHE_DIR)
rm -rf "${TMPBASE}com.apple.chrono" "${CACHEBASE}com.apple.chrono" 2>/dev/null
rm -rf "${CACHEBASE}com.tokeneater.app" "${CACHEBASE}com.claudeusagewidget.app" 2>/dev/null
# 6. Unregister widget plugins
pluginkit -r -i com.tokeneater.app.widget 2>/dev/null
pluginkit -r -i com.claudeusagewidget.app.widget 2>/dev/null
#