Getting Started

Prerequisites

  • macOS 14 (Sonoma) or later
  • A Claude Pro, Max, or Team plan (usage tracking requires an active subscription)
  • Claude Code installed (TokenEater reads your Claude credentials automatically)
TokenEater reads your Claude Code OAuth token from ~/.claude/.credentials.json. You don't need to configure anything manually.

Install

Download DMG (recommended)

Download TokenEater.dmg

Open the DMG, drag TokenEater to Applications, then:

  1. Double-click TokenEater in Applications - macOS will block it
  2. Open System Settings → Privacy & Security - scroll down to find the message about TokenEater
  3. Click Open Anyway and confirm
Do not use xattr -cr to bypass Gatekeeper - it prevents macOS from approving the widget extension, which will then be flagged as malware in the widget gallery. Always use System Settings → Open Anyway.

Homebrew

bash
brew tap AThevon/tokeneater
brew install --cask tokeneater

Update

TokenEater checks for updates automatically. When a new version is available, a modal lets you download and install it directly from the app - macOS will ask for your admin password.

If you installed via Homebrew: brew upgrade --cask tokeneater

Clean Reinstall

If something isn't working right, run a full clean reset (see the FAQ & Troubleshooting page for the complete script), then reinstall from the latest DMG.

Uninstall

bash
rm -rf /Applications/TokenEater.app
rm -rf ~/Library/Application\ Support/com.tokeneater.shared

If installed via Homebrew: brew uninstall --cask tokeneater

First Launch

  1. Open TokenEater from your Applications folder
  2. Grant Keychain access when prompted - this allows TokenEater to read your Claude Code credentials
  3. The app lives in your menu bar - look for the usage percentage
  4. To add a desktop widget: right-click your desktop → Edit Widgets → search "TokenEater"
After installing or updating, you may need to remove and re-add your widget for changes to take effect. macOS caches widget data aggressively.

Verify It Works

Once launched, you should see your current session usage percentage in the menu bar. Click it to open the detailed dashboard with ring gauges and pacing information.

If you see "0%" or no data, check that:

  • 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 file ~/.claude/.credentials.json exists