{"id":48085234,"url":"https://github.com/AThevon/TokenEater","last_synced_at":"2026-04-20T01:00:51.385Z","repository":{"id":339803396,"uuid":"1163421557","full_name":"AThevon/TokenEater","owner":"AThevon","description":"Native macOS app to monitor Claude AI usage limits and watch your coding sessions live","archived":false,"fork":false,"pushed_at":"2026-04-16T21:00:17.000Z","size":993,"stargazers_count":232,"open_issues_count":9,"forks_count":20,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-16T21:32:19.592Z","etag":null,"topics":["anthropic","claude","claude-code","macos","menu-bar","overlay","session-monitor","swift","swiftui","usage-monitor","widget","widgetkit"],"latest_commit_sha":null,"homepage":"https://tokeneater.vercel.app","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AThevon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"buy_me_a_coffee":"athevon"}},"created_at":"2026-02-21T15:58:30.000Z","updated_at":"2026-04-16T21:00:22.000Z","dependencies_parsed_at":"2026-03-04T19:00:55.870Z","dependency_job_id":null,"html_url":"https://github.com/AThevon/TokenEater","commit_stats":null,"previous_names":["athevon/tokeneater"],"tags_count":58,"template":false,"template_full_name":null,"purl":"pkg:github/AThevon/TokenEater","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AThevon%2FTokenEater","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AThevon%2FTokenEater/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AThevon%2FTokenEater/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AThevon%2FTokenEater/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AThevon","download_url":"https://codeload.github.com/AThevon/TokenEater/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AThevon%2FTokenEater/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32014823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude","claude-code","macos","menu-bar","overlay","session-monitor","swift","swiftui","usage-monitor","widget","widgetkit"],"created_at":"2026-04-04T15:14:13.315Z","updated_at":"2026-04-20T01:00:51.372Z","avatar_url":"https://github.com/AThevon.png","language":"Swift","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"TokenEaterApp/Assets.xcassets/AppIcon.appiconset/icon_256x256.png\" width=\"128\" height=\"128\" alt=\"TokenEater\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eTokenEater\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eMonitor your Claude AI usage limits directly from your macOS desktop.\u003c/strong\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://tokeneater.vercel.app\"\u003eWebsite\u003c/a\u003e · \u003ca href=\"https://tokeneater.vercel.app/en/docs\"\u003eDocs\u003c/a\u003e · \u003ca href=\"https://github.com/AThevon/TokenEater/releases/latest\"\u003eDownload\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/macOS-14%2B-111?logo=apple\u0026logoColor=white\" alt=\"macOS 14+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Swift-5.9-F05138?logo=swift\u0026logoColor=white\" alt=\"Swift 5.9\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/WidgetKit-native-007AFF?logo=apple\u0026logoColor=white\" alt=\"WidgetKit\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Claude-Pro%20%2F%20Max%20%2F%20Team-D97706\" alt=\"Claude Pro / Max / Team\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"MIT License\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/v/release/AThevon/TokenEater?color=F97316\" alt=\"Release\"\u003e\n  \u003ca href=\"https://buymeacoffee.com/athevon\"\u003e\u003cimg src=\"https://img.shields.io/badge/Buy%20Me%20a%20Coffee-FFDD00?logo=buymeacoffee\u0026logoColor=black\" alt=\"Buy Me a Coffee\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e **Requires a Claude Pro, Max, or Team plan.** The free plan does not expose usage data.\n\n## What is TokenEater?\n\nA native macOS menu bar app + desktop widgets + floating overlay that tracks your Claude AI usage in real-time.\n\n- **Menu bar** — Live percentages, color-coded thresholds, detailed popover dashboard\n- **Widgets** — Native WidgetKit widgets (usage gauges, progress bars, pacing) with reactive refresh\n- **Agent Watchers** — Floating overlay showing active Claude Code sessions with dock-like hover effect. Click to jump to the right terminal (Terminal.app, iTerm2, tmux, Kitty, WezTerm).\n- **Smart pacing** — Are you burning through tokens or cruising? Three zones: chill, on track, hot.\n- **Themes** — 4 presets + full custom colors. Configurable warning/critical thresholds.\n- **Notifications** — Alerts at warning, critical, and reset.\n\nSee all features in detail on the [website](https://tokeneater.vercel.app).\n\n## Install\n\n### Download DMG (recommended)\n\n**[Download TokenEater.dmg](https://github.com/AThevon/TokenEater/releases/latest/download/TokenEater.dmg)**\n\nOpen the DMG, drag TokenEater to Applications, then:\n\n1. Double-click TokenEater in Applications — macOS will block it\n2. Open **System Settings → Privacy \u0026 Security** — scroll down to find the message about TokenEater\n3. Click **Open Anyway** and confirm\n\n\u003e **Important:** Do not use `xattr -cr` to bypass this step — it prevents macOS from approving the widget extension, which will then be flagged as malware in the widget gallery.\n\n### Homebrew\n\n```bash\nbrew tap AThevon/tokeneater\nbrew install --cask tokeneater\n```\n\n### First Setup\n\n**Prerequisites:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (`claude` then `/login`). Requires a **Pro, Max, or Team plan**.\n\n1. Open TokenEater — a guided setup walks you through connecting your account\n2. Right-click on desktop \u003e **Edit Widgets** \u003e search \"TokenEater\"\n\n## Update\n\nTokenEater checks for updates automatically. When a new version is available, a modal lets you download and install it in-app — macOS will ask for your admin password to replace the app in `/Applications`.\n\nIf you installed via Homebrew: `brew update \u0026\u0026 brew upgrade --cask tokeneater`\n\n## Uninstall\n\nDelete `TokenEater.app` from Applications, then optionally clean up shared data:\n```bash\nrm -rf /Applications/TokenEater.app\nrm -rf ~/Library/Application\\ Support/com.tokeneater.shared\n```\n\nIf installed via Homebrew: `brew uninstall --cask tokeneater`\n\n## Build from source\n\n```bash\n# Requirements: macOS 14+, Xcode 16.4+, XcodeGen (brew install xcodegen)\n\ngit clone https://github.com/AThevon/TokenEater.git\ncd TokenEater\nxcodegen generate\nplutil -insert NSExtension -json '{\"NSExtensionPointIdentifier\":\"com.apple.widgetkit-extension\"}' \\\n  TokenEaterWidget/Info.plist 2\u003e/dev/null || true\nxcodebuild -project TokenEater.xcodeproj -scheme TokenEaterApp \\\n  -configuration Release -derivedDataPath build build\ncp -R \"build/Build/Products/Release/TokenEater.app\" /Applications/\n# Then approve via System Settings → Privacy \u0026 Security → Open Anyway\n```\n\n## Architecture\n\n```\nTokenEaterApp/           App host (settings, OAuth, menu bar, overlay)\nTokenEaterWidget/        Widget Extension (WidgetKit, reactive refresh)\nShared/                  Shared code (services, stores, models, pacing)\n  ├── Models/            Pure Codable structs\n  ├── Services/          Protocol-based I/O (API, TokenProvider, SharedFile, Notification, SessionMonitor)\n  ├── Repositories/      Orchestration (UsageRepository)\n  ├── Stores/            ObservableObject state containers\n  └── Helpers/           Pure functions (PacingCalculator, MenuBarRenderer, JSONLParser)\n```\n\nThe app reads Claude Code's OAuth token silently from the macOS Keychain (`kSecUseAuthenticationUISkip`), calls the Anthropic usage API, and writes results to a shared JSON file. A `TokenFileMonitor` watches for credential changes via FSEvents and triggers immediate refresh. The widget reads the shared file — it never touches the network or Keychain. The Agent Watchers overlay scans running Claude Code processes every 2s using macOS system APIs and tail-reads their JSONL logs.\n\n## How it works\n\n```\nGET https://api.anthropic.com/api/oauth/usage\nAuthorization: Bearer \u003ctoken\u003e\nanthropic-beta: oauth-2025-04-20\n```\n\nReturns `utilization` (0–100) and `resets_at` for each limit bucket.\n\n## Security \u0026 Privacy\n\nTokenEater reads an **OAuth access token** from the Claude Code keychain entry - the same standard token that Claude Code itself uses. At first launch, macOS will prompt you to allow this access; this is normal macOS behavior for any app reading a keychain item it didn't create.\n\n**What the app does with the token:**\n- Calls `GET /api/oauth/usage` (your current usage stats)\n- Calls `GET /api/oauth/profile` (your plan info)\n\n**What the app cannot do:** send messages, read conversations, modify your account, or access anything beyond read-only usage data.\n\nThe token never leaves your machine except for these two API calls to `api.anthropic.com`. The widget reads a local JSON file and has no network or keychain access at all.\n\nAnthropic does not currently offer a third-party OAuth flow or scoped API tokens - reading the existing token from the keychain is the only option. If scoped tokens become available, TokenEater will adopt them immediately. The entire codebase is open source and auditable: keychain access is in [`KeychainService.swift`](Shared/Services/KeychainService.swift), API calls in [`APIClient.swift`](Shared/Services/APIClient.swift).\n\n## Troubleshooting\n\n### Common issues\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| \"Rate limited\" or \"API unavailable\" | Your OAuth token has hit its per-token request limit | Run `claude /login` in your terminal for a fresh token - TokenEater detects the change and recovers automatically within seconds |\n| Keychain popup every few hours | macOS re-validates app signatures after updates | Click **Always Allow** - if it persists, run a clean reset |\n| Widget stuck / not updating | macOS caches widget extensions aggressively | Remove the widget, run a clean reset, re-add the widget |\n| App flagged as malware in widget gallery | `xattr -cr` was used instead of System Settings approval | Run a clean reset, reinstall, and approve via **System Settings \u003e Privacy \u0026 Security \u003e Open Anyway** |\n\n### Clean reset\n\nIf something is broken and you want to start fresh, run this in your terminal. It kills all related processes, wipes caches, preferences, and containers, then removes the app:\n\n```bash\n# 1. Kill processes\nkillall TokenEater NotificationCenter chronod cfprefsd 2\u003e/dev/null; sleep 1\n\n# 2. Wipe preferences\ndefaults delete com.tokeneater.app 2\u003e/dev/null\ndefaults delete com.claudeusagewidget.app 2\u003e/dev/null\nrm -f ~/Library/Preferences/com.tokeneater.app.plist\nrm -f ~/Library/Preferences/com.claudeusagewidget.app.plist\n\n# 3. Wipe sandbox containers\nfor c in com.tokeneater.app com.tokeneater.app.widget com.claudeusagewidget.app com.claudeusagewidget.app.widget; do\n    d=\"$HOME/Library/Containers/$c/Data\"\n    [ -d \"$d\" ] \u0026\u0026 rm -rf \"$d/Library/Preferences/\"* \"$d/Library/Caches/\"* \"$d/Library/Application Support/\"* \"$d/tmp/\"* 2\u003e/dev/null\ndone\n\n# 4. Wipe shared data and caches\nrm -rf ~/Library/Application\\ Support/com.tokeneater.shared\nrm -rf ~/Library/Application\\ Support/com.claudeusagewidget.shared\nrm -rf ~/Library/Caches/com.tokeneater.app\nrm -rf ~/Library/Group\\ Containers/group.com.claudeusagewidget.shared\n\n# 5. Wipe WidgetKit caches (critical - macOS keeps old widget binaries here)\nTMPBASE=$(getconf DARWIN_USER_TEMP_DIR)\nCACHEBASE=$(getconf DARWIN_USER_CACHE_DIR)\nrm -rf \"${TMPBASE}com.apple.chrono\" \"${CACHEBASE}com.apple.chrono\" 2\u003e/dev/null\nrm -rf \"${CACHEBASE}com.tokeneater.app\" \"${CACHEBASE}com.claudeusagewidget.app\" 2\u003e/dev/null\n\n# 6. Unregister widget plugins\npluginkit -r -i com.tokeneater.app.widget 2\u003e/dev/null\npluginkit -r -i com.claudeusagewidget.app.widget 2\u003e/dev/null\n\n# 7. Remove the app\nrm -rf /Applications/TokenEater.app\n```\n\n\u003e Some `Operation not permitted` errors on container metadata files are normal - macOS protects those, but the actual data is cleaned.\n\nAfter this, reinstall from the [latest release](https://github.com/AThevon/TokenEater/releases/latest/download/TokenEater.dmg) or via Homebrew, then **remove old widgets from your desktop and add them again** (right-click \u003e Edit Widgets \u003e TokenEater).\n\n## Support\n\nIf TokenEater saves you from hitting your limits blindly, consider [buying me a coffee](https://buymeacoffee.com/athevon) ☕\n\n## License\n\nMIT\n\n","funding_links":["https://buymeacoffee.com/athevon"],"categories":["Companion Apps \u0026 GUIs"],"sub_categories":["Quick Setup with cc-safe-setup"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAThevon%2FTokenEater","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAThevon%2FTokenEater","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAThevon%2FTokenEater/lists"}