Keychain helper

Install this if you're on Claude Code 2.1+ and TokenEater can't read your OAuth token. Optional otherwise.

Why a helper?

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 that gap.

What it does

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

When you need it

If you're on Claude Code 2.1+ and you don't have Claude Desktop installed alongside, 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: TokenEater will read directly from those higher-priority sources.

Install / remove

Open Settings -> Agent Watchers -> Keychain helper (or click the banner in the popover) and choose Install helper. macOS will run an AppleScript applet that registers the LaunchAgent. To remove it, click Remove helper in the same place.

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 tick, click Force sync now. It triggers a one-shot keychain read and rewrites the shared file in under a second.

Also useful if usage numbers seem stuck after reconnecting.

The helper is a transitional solution. Once the migration to a Developer Program signature is complete, it will be removed and the app will read directly from the keychain.