FAQ & Troubleshooting

Common issues

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:

# 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

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 (Free plans don't expose a usage endpoint)
• Claude Code is installed and you've signed in (claude /login in your terminal)
• The credentials file exists: ~/.claude/.credentials.json - or if you're on Claude Code 2.1+, the Keychain helper is installed (see the section below)
• Your internet connection is working (TokenEater calls the Anthropic API)

Session metrics (reset countdown, session pacing) don't show in the menu bar

You've toggled Session reset countdown or Session pacing in Settings → Display, the preview shows them, but nothing appears in the actual menu bar. Three likely causes:

1. No active session in the last ~5 hours. Anthropic's API only returns a 5h bucket (with a resets_at timestamp) when there's an active session. Run claude in your terminal, wait for the next API tick, and the metrics will appear.
2. You're on a Free plan. The 5h bucket is only returned for Pro, Max, Team, and Enterprise subscriptions. The weekly bucket is exposed to all plans - that's why weekly pacing works while session metrics don't.
3. Claude Code 2.1+ without the Keychain helper installed. The app can't read a token, so every API call fails silently and the stored values stay frozen. Install the helper (see below).

Keychain helper (Claude Code 2.1+)

Starting with Claude Code 2.1, the OAuth token is stored exclusively in the macOS Keychain behind an ACL that only whitelists /usr/bin/security. A sandboxed ad-hoc-signed app like TokenEater can't reach it directly, so v4.10.0 ships an opt-in helper to bridge the gap.

What it does. The helper is a tiny non-sandboxed binary that shells out to /usr/bin/security, reads the Claude Code token from the Keychain on a configurable interval (30s minimum, default 5min), and writes it atomically to ~/Library/Application Support/com.tokeneater.shared/keychain-token.json with 0600 permissions. TokenEater reads that file as a second-priority token source. Zero network calls. Full source on GitHub.

When you need it. If you're on Claude Code 2.1+ and don't also have Claude Desktop installed, the app will display an onboarding banner prompting you to install it. If you still have ~/.claude/.credentials.json (older Claude Code) or Claude Desktop (which keeps a decryptable config.json), the helper is optional.

Install / Remove. Open Settings → Agent Watchers → Keychain helper (or the banner in the popover) and click Install helper. macOS will prompt you to run a small AppleScript applet that registers the LaunchAgent. To remove it, click Remove helper in the same section.

Force sync now. If you've just run claude /login and want TokenEater to pick up the new token immediately without waiting for the next helper tick, click Force sync now. It triggers a one-shot Keychain read and rewrites the shared file in under a second. Use this also if you see stale usage numbers after logging back in.

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 5 minutes by default (configurable, minimum 3 minutes). The menu bar reset countdown ticks every minute without hitting the API. You can adjust the polling interval in Settings → Performance.

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 a few real-time features (Agent Watchers, animated gradient background) that can nudge 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. Turn off the animated gradient background
4. Increase the API polling interval

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