TokenEater: a macOS menu bar monitor for Claude usage limits

The paid-plan gap TokenEater fills

Claude's web interface shows usage, but it is a browser tab you have to remember to open. Claude Code, the CLI, keeps its own session logs on disk and holds an OAuth token in the macOS Keychain, yet neither surface gives you a persistent, glanceable number. TokenEater targets that gap for one specific group: developers on a paid Claude plan who run Claude Code and want the remaining quota visible while they work.

The README states the constraint plainly: a Claude Pro, Max or Team plan is required, and the free plan does not expose usage data. That is not a design decision by the app author. It follows from what the underlying API returns. If you are on the free tier, no amount of configuration will make TokenEater useful, because there is no usage endpoint to read.

The app is Swift 5.9 and targets macOS 14 or later, distributed as a notarized DMG and through a Homebrew cask. It is not a web dashboard and not a cross-platform tool. That narrowness is the point: a menu bar item, WidgetKit widgets and a floating overlay are all native macOS surfaces.

Two read-only calls and a Keychain token

The mechanism is short enough to describe in full. TokenEater reads the OAuth access token that Claude Code already stored in your macOS Keychain, the same token the CLI uses. It does not create a token, and the README notes that Anthropic does not currently offer a third-party OAuth flow or scoped tokens, so reading the existing one is the only path an app like this has.

With that token, the app makes exactly two requests, both GET and both read-only: one to the usage endpoint for current statistics, one to the profile endpoint for plan information. The README states the app cannot send messages, read conversations or modify your account. The token does not leave the machine except for those two calls.

Everything else is local. The History tab and Agent Watchers read Claude Code's session logs on disk. The widget reads a local JSON file and, per the README, has no network or keychain access at all. That separation matters: the widget cannot leak a token because it never touches one.

The Keychain prompt is the friction point. At first launch macOS asks whether to allow the read, and you click Always Allow once. The README explains why the prompt does not return on updates: the read goes through Apple's own security tool, whose signature never changes. That is a real explanation rather than a hand-wave, and it is the kind of detail that usually goes undocumented in menu bar utilities.

Installing TokenEater and connecting your account

The README recommends the DMG. Download it from the latest release, open it, drag TokenEater to Applications and launch. The build is signed with a Developer ID and notarized by Apple, so Gatekeeper allows the first launch without the usual right-click workaround.

The Homebrew route needs three commands. The README notes that brew trust is required on Homebrew 6.0 and later, because that version no longer loads a third-party tap until you trust it.

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

Before any of this, the prerequisite is Claude Code installed and authenticated. The README gives the sequence: run claude, then /login. You also need a Pro, Max or Team plan, since the free tier exposes no usage data.

On first launch a guided setup walks you through connecting the account, which is where the macOS Keychain prompt appears. Click Always Allow once.

To add a desktop widget, the README gives a two-step path: right-click the desktop, choose Edit Widgets, then search for TokenEater. The widget renders gauges, progress bars and pacing from the local JSON file rather than from the network.

Smart Color and pacing: the parts that are not just a number

A raw percentage is not very informative on its own. TokenEater's Smart Color blends how much you have used with how fast you are burning, so the color shifts before the number looks alarming. Three temperaments control how cautious that shift is. Smart pacing sorts your current rate into four zones the README names: chill, on track, warning and hot.

This is the most opinionated part of the app, and it is worth being clear about the trade-off. A blended color is a heuristic, not a measurement. Two users at the same 60 percent will see different colors if their burn rates differ, which is the intent, but it also means the color is not a stable reference you can compare across a team. If you want a plain number, the percentages are still there.

The dashboard itself is composable. The README describes a popover you build element by element from rings, chips, arcs and pacing bars at full, half or third width, starting from built-in templates and saving your own. The main window has three spaces: Monitoring, History and Settings, with flippable tiles and 7-day sparklines.

History comes from Claude Code's local logs. You get a stacked chart by model, a project ranking, session counts and cache hit rate, filterable by model family across ranges from 24 hours to 90 days. Because the source is local logs, the depth of that history depends on what Claude Code has retained, not on what TokenEater stores.

Agent Watchers and what the overlay can and cannot do

Agent Watchers is a floating overlay listing your live Claude Code sessions across terminals and VSCode-family editors. The README lists Terminal, iTerm2, tmux, Kitty and WezTerm as jump targets: click a session to focus its terminal or editor, right-click for quick actions.

This is the feature with the narrowest applicability, and the README does not pretend otherwise. It is macOS-only and it works by reading local session logs and matching sessions to terminal windows. If you run Claude Code inside a container, over SSH from a remote host, or in an editor not in that list, the overlay has less to bind to. The README does not document a fallback for those cases.

The notification surface is broad: per-surface and per-event toggles covering escalation, recovery, pacing, scheduled reset reminders, extra credits and token expiry. That is a lot of switches, and the README does not describe defaults for each one, so the practical behaviour on a fresh install is something you will discover in Settings rather than read about in advance.

Updating, uninstalling and the licence terms

TokenEater checks for updates on its own. When a version is available, a modal lets you download and install it in-app, and macOS asks for your admin password to replace the app in /Applications. If you installed through Homebrew, the README gives the alternative:

brew update && brew upgrade --cask tokeneater

Uninstalling is a manual deletion plus optional cleanup. The README provides the commands for both the app bundle and the shared application support directory:

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

Homebrew users get brew uninstall --cask tokeneater instead. The README points to a clean reset in the troubleshooting guide for a complete wipe including caches and widget state, which suggests the plain deletion leaves something behind. That is a small but real operational detail.

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. This is a description of the licence text, not legal advice; if you plan to redistribute a modified build, read the LICENSE file in the repository rather than this summary. Note that the MIT licence covers the source in the repository, while the notarized DMG is a build artifact of it.

Where TokenEater is the wrong tool

The clearest failure mode is the plan tier. On a free Claude plan there is no usage data to expose, so the app has nothing to display and no workaround exists in the README.

The second is the Keychain dependency. TokenEater works because it reads a credential another application created. If your security posture forbids granting an unfamiliar app access to that item, the app cannot function, and there is no alternative authentication path documented, because Anthropic does not yet offer scoped tokens. The README acknowledges this directly and says the app will adopt scoped tokens if they become available. Until then, you are trusting a third-party binary with a token that can call the Anthropic API. The README argues the relevant code is short and auditable, which is a fair point for a Swift project of this size, but auditing it is on you.

The third is platform. This is a SwiftUI app for macOS 14 and later. Linux, Windows and WSL users have no version of it. If your team runs Claude Code in CI or on remote build machines, TokenEater will not report on those sessions, since it monitors the desktop where it is installed.

Finally, the History charts inherit whatever Claude Code's local logs contain. If logs are pruned, rotated or stored somewhere unusual, the charts thin out. The README does not document a retention policy or a way to point the app at a different log location.

How TokenEater differs from generic Claude usage tools

The related searches around this project point at a cluster of tools in the same space: ClaudeMeter, Usage4Claude, Claude AI widget, Claude credits check. The README does not compare TokenEater to any of them, so the difference has to be read off the architecture rather than a feature table.

The distinguishing choice here is that TokenEater is a native macOS application rather than a browser extension or a web page. That buys WidgetKit widgets, a menu bar item, a floating overlay and the ability to focus a terminal window by clicking a session. A browser extension can show a number; it cannot jump you to the tmux pane where a session is running, and it cannot place a gauge on the desktop.

The cost of that choice is reach. A web-based or extension-based tool works wherever the browser works, including Linux and Windows. TokenEater works on macOS 14 and later and nowhere else. If your constraint is cross-platform coverage, the native approach is a liability rather than an advantage.

The second difference is the data source split. TokenEater combines a live API read for current limits with local Claude Code logs for history. A tool that only polls the API can show you the percentage but not which project consumed it. A tool that only parses logs can show you history but not your remaining quota. TokenEater does both, which is why it needs both Keychain access and filesystem access.

Editorial conclusion

Adopt TokenEater if you already run Claude Code on a Pro, Max or Team plan and want usage visible without opening a browser tab; the paid-plan requirement is a hard gate, and the free plan exposes no usage data, so the app has nothing to show. Skip it if you want a cross-platform tool, if you are unwilling to grant Keychain access to the token Claude Code created, or if you need headless or CI-side reporting, since this is a SwiftUI desktop app. Before installing, confirm your plan tier, read the privacy section of the README to see exactly which two endpoints are called, and check the troubleshooting guide if you want a clean uninstall that removes the shared application support directory.

Frequently asked questions

Official sources

1. AThevon/TokenEater on GitHub
2. License: MIT
3. Project website
4. README
5. Releases