FAQ & Troubleshooting

Common issues

"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 picks it up automatically.

Error persists for hours

The app backs off for ~6h after token exhaustion.

Click Retry now in the menu bar popover after running claude /login.

Keychain popup every few hours

macOS re-validates app signatures after updates.

Click Always Allow - if it persists, run a clean reset.

Widget stuck / not updating

macOS caches widget extensions aggressively.

Remove the widget, run a clean reset, re-add the widget.

App flagged as malware in widget gallery

xattr -cr was used instead of System Settings approval.

Run a clean reset, reinstall, and approve via System Settings → Privacy & Security → Open Anyway.

Clean reset

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:

bash
# 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

# 7. Remove the app
rm -rf /Applications/TokenEater.app
Some "Operation not permitted" errors on container metadata files are normal - macOS protects those, but the actual data is cleaned.

After this, reinstall from the latest release or via Homebrew, then remove old widgets from your desktop and add them again (right-click → Edit Widgets → TokenEater).

Usage shows 0% or no data

Check the following:

  • You have an active Claude Pro, Max, or Team subscription
  • Claude Code is installed and you've signed in (claude /login in your terminal)
  • The credentials file exists: ~/.claude/.credentials.json
  • Your internet connection is working (TokenEater calls the Anthropic API)

Widget appears blank

This usually happens after a system update or TokenEater update:

  1. Remove the widget
  2. Restart your Mac (or run killall NotificationCenter chronod)
  3. Re-add the widget

If that doesn't work, run the full clean reset above.

Which terminals are supported for Agent Watchers?

Agent Watchers detects Claude Code sessions via system processes, so it works with virtually any terminal or IDE. Confirmed support includes:

  • iTerm2, WezTerm, Terminal.app, Warp, Ghostty
  • VS Code, Cursor, Windsurf, Zed, and other VS Code-based editors
  • tmux and screen sessions (within any terminal)

If your terminal runs Claude Code, Agent Watchers will find it.

How often does usage data refresh?

TokenEater polls the Anthropic API every 30 seconds by default. The refresh interval is visible in the dashboard.

Does TokenEater send my data anywhere?

No. TokenEater only communicates with the Anthropic API (api.anthropic.com) to fetch your usage data. No analytics, no telemetry, no third-party services. The app is open source - you can verify this yourself.

High CPU usage

TokenEater includes several real-time features (Agent Watchers, animated dashboard, particle effects) that can increase CPU usage. If this is a concern:

  1. Open TokenEater settings → Performance section
  2. Disable Agent Watchers if you don't need session monitoring
  3. Reduce animation intensity or disable particle effects
  4. Increase the API polling interval

These options let you balance features vs. resource usage to suit your setup.