Common issues

Find your symptom, apply the fix. For any connection problem, try Settings -> Providers -> Reset connection first: it rereads the credentials and keeps all your settings.

Claude connection

"Usage API throttled by Anthropic" or "Rate limited"

Run claude /login for a fresh token, then click Retry now in the popover banner. Otherwise TokenEater retries on its own, waiting longer each time (30 min up to 6 h).

"Authorization needed" that will not go away

Settings -> Providers -> Reset connection. If it persists, Copy diagnostic shows the token source, Keychain result and token expiry, with no credentials in it.

Several "Claude Code-credentials" items in the Keychain

TokenEater keeps the one with a real login. If none has one, sign in to Claude Code again or delete the extra item in Keychain Access. See Keychain access.

"macOS refused access" or "Reading the Keychain timed out"

Allow access when macOS asks, then try again. If it keeps timing out, restart TokenEater.

Keychain popup about "Claude Code-credentials"

Click Always Allow once. It sticks across updates.

OpenAI Codex connection

Codex not logged in, or login expired

Open Codex or run codex login, then click Check connection in Settings -> Providers. Only a ChatGPT login stored in a file works: API-key and Keychain-stored logins are not supported.

"API-key mode: no usage limits to track"

Codex widget empty or off

Turn Codex on in Settings -> Providers, refresh Monitoring, then add Codex Usage from Edit Widgets. Still stale: full clean.

Widgets

Widget stuck or not updating

Remove the widget, run a full clean, re-add it.

Widget empty after an update

Remove the widget, restart your Mac (or run killall NotificationCenter chronod), re-add it. Still empty: full clean.

Widget flagged as malware

You are running a local build that is not notarized. Install the official DMG from the latest release, or allow it in System Settings -> Privacy & Security -> Open Anyway.

Missing usage data

0% or no data

No readable login for that provider (Claude Code token or Codex CLI login), or an account with no usage data (Claude Free plan, Codex API-key account). Full checklist in Verify install.

Session metrics missing from the menu bar

The provider is off or hidden by the mode switch, no 5h window is running, or your Codex plan has no session window. See Verify install.

Agent Watchers (Claude only)

A session is missing

Update the Claude Code extension: the old 2.0.x versions are not detected.