TokenEaterTokenEater/Docs

Getting Started

Prerequisites

  • macOS 14 (Sonoma) or later
  • A Claude Pro 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

Install via Homebrew (recommended):

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

Or download the latest DMG from the GitHub Releases page.

Update

bash
brew upgrade --cask tokeneater

Clean Reinstall

If something isn't working right, a clean reinstall often fixes it:

bash
brew uninstall --cask tokeneater
brew install --cask tokeneater

Uninstall

bash
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 or Team subscription
  • Claude Code is installed and you've signed in (claude /login in your terminal)
  • The file ~/.claude/.credentials.json exists