Summary

TokenEater is a native macOS app for real-time Claude AI usage monitoring and live coding session tracking. It targets Pro, Max, or Team plan users, offering a desktop solution to prevent token limit breaches and enhance workflow visibility by providing immediate AI usage insights.

How It Works

This native macOS app uses a menu bar, WidgetKit extensions, and a floating overlay. It securely reads Claude AI OAuth tokens from the Keychain, queries Anthropic's usage/profile APIs for real-time data, and writes results to a shared local JSON file. Widgets access this file without network/Keychain permissions. An overlay monitors active Claude Code processes via JSONL log tailing, enabling quick terminal session navigation.

Quick Start & Requirements

Install via DMG or Homebrew (brew tap AThevon/tokeneater && brew install --cask tokeneater). Building from source requires macOS 14+, Xcode 16.4+, and XcodeGen. Prerequisites: Claude Code installed/authenticated and a Claude Pro, Max, or Team subscription (free plans lack data exposure). Initial setup is guided. Links to website, docs, and DMG are provided.

Highlighted Details

• Menu bar app: live usage percentages, color-coded thresholds, detailed dashboard.
• Native WidgetKit widgets: usage gauges, progress bars, pacing.
• "Agent Watchers" overlay: tracks active Claude Code sessions with one-click terminal jump.
• "Smart pacing": categorizes usage into "chill," "on track," "hot" zones.
• Customizable themes, thresholds, and system notifications.

Maintenance & Community

Automatic in-app updates are provided via modal prompts. Homebrew users upgrade with brew update && brew upgrade --cask tokeneater. A "Buy me a coffee" link supports the project. Official documentation and a website are linked.

Licensing & Compatibility

Released under the MIT license, offering permissive terms for commercial use and integration within closed-source applications without significant restrictions.

Limitations & Caveats

Monitoring is limited to Claude Pro, Max, or Team plans; free tiers are unsupported. Functionality relies on Anthropic's current API and Keychain access methods. Users must approve Keychain access and widget extensions via System Settings to avoid malware flagging. A comprehensive "clean reset" script is available for troubleshooting.