{"id":46713946,"url":"https://github.com/richyparr/tokemon","last_synced_at":"2026-03-09T10:01:09.427Z","repository":{"id":338972532,"uuid":"1157729523","full_name":"richyparr/tokemon","owner":"richyparr","description":"Free, open-source Claude usage monitor for macOS \u0026 Raycast. Track token limits, burn rate, per-project costs, team budgets, and get alerts before you hit rate limits.","archived":false,"fork":false,"pushed_at":"2026-03-08T14:12:17.000Z","size":26404,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-08T16:14:22.494Z","etag":null,"topics":["anthropic","claude","claude-code","macos","menu-bar","open-source","rate-limit","raycast","swift","token-usage"],"latest_commit_sha":null,"homepage":null,"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/richyparr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2026-02-14T07:44:38.000Z","updated_at":"2026-03-08T14:50:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"f729b934-a950-4417-b8b4-010739cab5d6","html_url":"https://github.com/richyparr/tokemon","commit_stats":null,"previous_names":["richyparr/tokemon"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/richyparr/tokemon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richyparr%2Ftokemon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richyparr%2Ftokemon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richyparr%2Ftokemon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richyparr%2Ftokemon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/richyparr","download_url":"https://codeload.github.com/richyparr/tokemon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richyparr%2Ftokemon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30290891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","open-source","rate-limit","raycast","swift","token-usage"],"created_at":"2026-03-09T10:00:45.705Z","updated_at":"2026-03-09T10:01:09.420Z","avatar_url":"https://github.com/richyparr.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tokemon\n\nA macOS menu bar app that monitors your Claude usage in real-time so you never hit a rate limit by surprise.\n\n![macOS 14+](https://img.shields.io/badge/macOS-14.0%2B-blue)\n![Swift 6](https://img.shields.io/badge/Swift-6.0-orange)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n## What it does\n\nTokemon sits in your menu bar and shows your current Claude usage at a glance. It reads your session data automatically — no API keys to configure, no manual setup. Just install and go.\n\n**Who it's for:** Developers on Claude Pro, Team, or Enterprise plans who use Claude Code or claude.ai and want to keep an eye on their rate limits.\n\n## Features\n\n### Menu bar monitoring\n- Live usage percentage in your menu bar with color-coded severity (green/orange/red)\n- 5 icon styles: percentage text, battery, progress bar, icon + bar, compact number\n- Optional monochrome mode to match native macOS menu bar styling\n- Click to see detailed usage breakdown with reset timer\n\n### Floating window\n- Always-on-top compact window showing usage percentage\n- Configurable rows: 5-hour session, 7-day rolling, 7-day Sonnet\n- Remembers position between sessions\n- Toggle from the right-click context menu\n\n### Alerts \u0026 notifications\n- Configurable warning thresholds (50–90%)\n- macOS system notifications when approaching limits\n- Session reset notifications when usage drops back to 0%\n- Webhook alerts to **Slack** and **Discord** with customizable templates\n\n### Multi-profile support\n- Manage multiple accounts/profiles\n- Switch between profiles from the popover\n- Per-profile alert thresholds\n- Credentials synced from system Keychain or entered manually\n\n### Analytics \u0026 export\n- Usage trend charts with burn rate calculation\n- 30/90-day usage history\n- Project-by-project token breakdown (via JSONL logs)\n- Export to PDF, CSV, or shareable usage cards\n\n### Budget tracking (Admin API)\n- Organization admins can connect an Admin API key\n- Monthly budget gauge with cost forecasting\n- Per-project cost breakdown\n- Auto-alerts at 50%, 75%, 90% of budget\n- Team member usage visibility\n\n### Terminal integration\n- Export usage to `~/.tokemon/statusline` for shell prompt integration\n- JSON status at `~/.tokemon/status.json` for custom scripts\n- Configurable format with ANSI colors\n- One-click shell integration (zsh/bash)\n\n### Theming\n- Native (follows system light/dark), Light, or Dark theme\n- Dark theme with warm orange accents\n\n## Installation\n\n### Download (recommended)\n\n1. Download `Tokemon.zip` from the [latest release](https://github.com/richyparr/tokemon/releases/latest)\n2. Unzip and move `Tokemon.app` to `/Applications`\n3. The app is not yet notarized, so you need to remove the quarantine flag:\n   ```bash\n   xattr -cr /Applications/Tokemon.app\n   ```\n4. Double-click to open\n\n### Build from source\n\nRequires Xcode 15+ and [XcodeGen](https://github.com/yonaskolb/XcodeGen).\n\n```bash\ngit clone https://github.com/richyparr/tokemon.git\ncd tokemon\nxcodegen generate\nxcodebuild build -scheme Tokemon -destination 'platform=macOS,arch=arm64' -configuration Release\n```\n\nThe built app will be in your Xcode DerivedData directory.\n\n## How it works\n\nTokemon reads your usage through two data sources:\n\n1. **OAuth** (primary) — Queries the usage endpoint using credentials from your macOS Keychain. This gives you accurate 5-hour session percentages, 7-day rolling usage, and reset timers. Credentials are picked up automatically if you're signed into Claude Code.\n\n2. **JSONL logs** (fallback) — Parses local conversation logs in `~/.claude/projects/` to estimate token usage when OAuth isn't available.\n\nNo data leaves your machine except calls to the usage endpoint. No telemetry, no analytics, no accounts.\n\n## Requirements\n\n- macOS 14.0 (Sonoma) or later\n- A Claude Pro, Team, or Enterprise subscription\n- For budget/team features: an Admin API key\n\n## Settings\n\nRight-click the menu bar icon or press Cmd+, to access settings:\n\n| Tab | What it configures |\n|-----|--------------------|\n| **Profiles** | Add/manage accounts, sync from Keychain |\n| **General** | Refresh interval, data sources, launch at login |\n| **Appearance** | Theme, menu bar icon style, monochrome mode |\n| **Notifications** | Alert thresholds, Slack/Discord webhooks |\n| **Terminal** | Statusline export format, shell integration |\n| **Analytics** | Usage history charts, PDF/CSV export |\n| **Budget** | Monthly spending limits, cost forecasting |\n| **Admin** | Admin API key connection |\n\n## Privacy\n\n- All data is stored locally on your Mac\n- Credentials are stored in the macOS Keychain\n- The only network calls are to the usage and token refresh endpoints\n- No telemetry, tracking, or third-party services\n- The app is not sandboxed (it needs access to `~/.claude` for JSONL parsing)\n\n## Support\n\n- [Report issues](https://github.com/richyparr/tokemon/issues)\n- Website: [tokemon.ai](https://tokemon.ai)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frichyparr%2Ftokemon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frichyparr%2Ftokemon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frichyparr%2Ftokemon/lists"}