TokenEaterTokenEater/Docs

FAQ & Troubleshooting

Widget doesn't update after upgrading

macOS aggressively caches WidgetKit extensions. After updating TokenEater:

  1. Remove the old widget from your desktop
  2. Add a fresh one (right-click desktop → Edit Widgets → TokenEater)

If that doesn't work, clear the WidgetKit cache:

bash
killall NotificationCenter chronod

Then re-add the widget.

Prompted for Keychain password repeatedly

TokenEater reads your Claude Code OAuth token from the macOS Keychain. If you're being prompted repeatedly:

  1. Open Keychain Access
  2. Search for "Claude" or "anthropic"
  3. Double-click the entry → Access Control tab
  4. Add TokenEater to the allowed applications list
TokenEater uses silent Keychain reads for automatic refreshes. The password prompt should only appear once during initial setup.

Usage shows 0% or no data

Check the following:

  • You have an active Claude Pro 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

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.