Noureddine RAMDI / TokenEater: real-time Claude AI usage monitoring on macOS with process overlays

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1032 Words
github-stars swift macos menu-bar-app widgetkit process-monitoring oauth

AThevon/TokenEater

TokenEater tackles a practical pain point for users of Anthropic’s Claude AI on macOS: tracking your usage limits in real-time without switching contexts or digging through logs. It combines OAuth token reading from the macOS Keychain with live API polling and a clever floating overlay that monitors your local Claude Code processes, giving you a continuous, at-a-glance view of your AI usage and session states.

What TokenEater does and how it works

At its core, TokenEater is a native macOS menu bar application written in Swift and SwiftUI. It targets users subscribed to Claude AI’s Pro, Max, or Team plans, tapping into their OAuth tokens stored securely in the macOS Keychain to query Anthropic’s usage API.

The app surfaces usage data through multiple interfaces: the macOS menu bar, native WidgetKit widgets for your desktop or Notification Center, and most notably, a floating “Agent Watchers” overlay. This overlay is a unique feature that scans running Claude Code processes every two seconds using macOS system APIs. It reads their JSONL logs live from disk and displays a floating HUD with dock-like hover effects that let you jump directly to the relevant terminal session. Supported terminals include Terminal.app, iTerm2, tmux, Kitty, and WezTerm.

Architecturally, TokenEater is split into three main components:

  • TokenEaterApp: The main app host handling settings, OAuth authentication flows, menu bar UI, and the Agent Watchers overlay.
  • TokenEaterWidget: A WidgetKit extension that provides native widgets for usage monitoring, designed with security in mind—it has no network or keychain access.
  • Shared: A shared services layer containing pure Codable models, API services, pacing analysis, and stores managing the app’s state and logic.

The pacing analysis component categorizes usage into four zones, applying smart color-coded risk scoring with configurable temperaments. This helps users gauge their consumption patterns and avoid surprises. Additionally, a history browser reads from Claude Code’s local JSONL logs, allowing filtering by model family and time range.

Technical strengths and design tradeoffs

The standout technical feature is the Agent Watchers overlay, which bridges local process monitoring with API usage data to provide an integrated observability experience.

Scanning running processes every two seconds is non-trivial on macOS, and TokenEater leverages appropriate system APIs to do this efficiently and securely. Tail-reading JSONL logs directly from disk lets it provide up-to-the-second session information without requiring intrusive instrumentation or changes to Claude Code itself.

The overlay’s ability to jump directly to the associated terminal session across multiple terminal emulators shows attention to developer workflows. Supporting Terminal.app, iTerm2, tmux, Kitty, and WezTerm covers most common setups, and hooking into these terminals across process boundaries demonstrates a clever use of macOS internals.

The app’s architecture cleanly separates concerns: the widget extension is sandboxed with zero network/keychain access, improving security and user trust. The main app handles sensitive OAuth tokens and network calls, while shared code is pure Swift models and services.

The tradeoff here is platform specificity and dependency on macOS 14+ and Xcode 16.4+. This limits portability but allows deep integration with macOS features like WidgetKit, native menu bar extras, and system APIs for process enumeration.

Overall, the codebase appears well-structured, with clear separation and idiomatic Swift usage. The pacing analysis and risk scoring add practical value beyond simple usage polling.

Getting started with TokenEater

The repository provides clear installation options:

Download the signed and notarized TokenEater.dmg, open it, drag the app to Applications, and launch. macOS Gatekeeper will allow first-run without extra steps.

Homebrew

Install via Homebrew:

brew tap AThevon/tokeneater
brew install --cask tokeneater

First setup

Prerequisites: Claude Code installed and authenticated (claude then /login), and a Pro, Max, or Team plan.

  1. Open TokenEater — a guided setup walks you through connecting your Claude account.
  2. Right-click on your desktop, select Edit Widgets, and search for “TokenEater” to add the native WidgetKit widgets.

Uninstall

Delete TokenEater.app from Applications and optionally remove shared data:

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

If installed via Homebrew:

brew uninstall --cask tokeneater

For developers building from source, the repo includes instructions to clone, generate the Xcode project with XcodeGen, and build:

git clone https://github.com/AThevon/TokenEater.git
cd TokenEater
xcodegen generate
plutil -insert NSExtension -json '{"NSExtensionPointIdentifier":"com.apple.widgetkit-extension"}' TokenEaterWidget/Info.plist 2>/dev/null || true
xcodebuild -project TokenEater.xcodeproj -scheme TokenEaterApp -configuration Release -derivedDataPath build build
cp -R "build/Build/Products/Release/TokenEater.app" /Applications/

who should consider using TokenEater

TokenEater is a solid choice for macOS users who actively work with Claude AI under Pro, Max, or Team plans and want continuous, non-intrusive visibility into their usage limits and session states.

Its tight integration with macOS system APIs and SwiftUI makes it a natural fit for developers comfortable in the Apple ecosystem who appreciate native UI experiences.

The Agent Watchers overlay is particularly useful for power users juggling multiple Claude Code terminals, offering real-time observability with direct navigation to terminal sessions.

The main limitations are its macOS 14+ requirement and reliance on Claude’s OAuth tokens, so it’s not suitable for users on older macOS versions or without appropriate Claude subscriptions.

Overall, TokenEater strikes a pragmatic balance between real-time usage monitoring, security (sandboxed widgets, keychain integration), and developer ergonomics. It’s a neat example of leveraging native platform capabilities to fill a niche that official APIs or tools don’t cover yet.

→ GitHub Repo: AThevon/TokenEater ⭐ 304 · Swift