{"id":47555900,"url":"https://github.com/theDanButuc/Claude-Usage-Monitor","last_synced_at":"2026-03-31T09:00:46.126Z","repository":{"id":346220178,"uuid":"1188958331","full_name":"theDanButuc/Claude-Usage-Monitor","owner":"theDanButuc","description":"A native macOS menu bar app that shows your Claude.ai usage at a glance — colour-coded icon, live counter, reset timer. No API key needed.","archived":false,"fork":false,"pushed_at":"2026-03-23T10:58:02.000Z","size":9119,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T12:53:07.950Z","etag":null,"topics":["ai-tools","anthropic","claude","claude-ai","developer-tools","macos","macos-app","menubar","menubar-app","swift","swiftui","usage-monitor"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theDanButuc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-03-22T20:08:30.000Z","updated_at":"2026-03-23T10:53:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/theDanButuc/Claude-Usage-Monitor","commit_stats":null,"previous_names":["thedanbutuc/claude-usage-monitor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/theDanButuc/Claude-Usage-Monitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theDanButuc%2FClaude-Usage-Monitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theDanButuc%2FClaude-Usage-Monitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theDanButuc%2FClaude-Usage-Monitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theDanButuc%2FClaude-Usage-Monitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theDanButuc","download_url":"https://codeload.github.com/theDanButuc/Claude-Usage-Monitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theDanButuc%2FClaude-Usage-Monitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31228492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-31T08:35:14.124Z","status":"ssl_error","status_checked_at":"2026-03-31T08:34:00.887Z","response_time":111,"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":["ai-tools","anthropic","claude","claude-ai","developer-tools","macos","macos-app","menubar","menubar-app","swift","swiftui","usage-monitor"],"created_at":"2026-03-29T11:00:26.339Z","updated_at":"2026-03-31T09:00:46.120Z","avatar_url":"https://github.com/theDanButuc.png","language":"Swift","funding_links":[],"categories":["ユーティリティ","AI","AIツール"],"sub_categories":["メニューバーツール","その他のツール"],"readme":"# ClaudeUsageMonitor\n\nA native macOS menu-bar app that tracks your [Claude.ai](https://claude.ai) usage in real time — no API key needed.\n\n\u003cimg src=\"ClaudeUsageMonitor/Assets/AppIcon_128.png\" width=\"128\" alt=\"App Icon\" /\u003e\n\n---\n\n## Screenshot\n\n\u003cimg src=\"screenshots/popover.png\" width=\"260\" alt=\"ClaudeUsageMonitor popover\" /\u003e\n\n---\n\n## Features\n\n- **Menu-bar only** — no Dock icon, stays out of your way\n- **Live usage counter** — shows `used/limit` (e.g. `45/100`) right in the menu bar\n- **Colour-coded tree icon** — green → yellow → red as usage climbs\n- **Popover dashboard** — circular progress ring, reset countdown, stats cards\n- **Session-aware** — captures Claude's internal rate-limit window via a fetch interceptor, not just the billing-period total\n- **Configurable auto-refresh** — 30s / 1m / 2m / 5m / 10m, set via right-click menu\n- **Native notifications** — alerts at 80%, 90%, 100% usage and on session reset\n- **Live reset countdown** — \"Resets in Xh Ym\" updates every minute while the popover is open; reset time sourced directly from Claude's API\n- **Stale data indicator** — icon turns grey and shows ⚠ if data is older than 10 minutes\n- **Right-click context menu** — quick usage info and settings without opening the popover\n- **In-app update banner** — notified when a new version is available on GitHub\n- **Persisted login** — WebKit stores your Claude session automatically; you only log in once\n\n---\n\n## Installation (recommended — pre-built DMG)\n\n\u003e **Requires macOS 13 Ventura or later.**\n\n### Step 1 — Download\n\nDownload the latest **ClaudeUsageMonitor.dmg** from the [Releases page](https://github.com/theDanButuc/Claude-Usage-Monitor/releases/latest).\n\n### Step 2 — Install\n\n1. Double-click `ClaudeUsageMonitor.dmg` to mount it\n2. Drag **ClaudeUsageMonitor** into the **Applications** folder shortcut\n\n### Step 3 — First launch (Gatekeeper bypass)\n\nBecause the app is **ad-hoc signed** (not yet notarized with an Apple Developer ID), macOS will block it on first open.\n\n**Do this once:**\n\n```\nRight-click ClaudeUsageMonitor.app → Open → Open\n```\n\nOr via Terminal:\n\n```bash\nxattr -cr /Applications/ClaudeUsageMonitor.app\nopen /Applications/ClaudeUsageMonitor.app\n```\n\n\u003e You will **not** need to do this again after the first successful launch.\n\n### Step 4 — Log in to Claude\n\nA browser window opens automatically on first run. Log in to your Claude.ai account normally. The window closes by itself when login succeeds and the tree icon appears in your menu bar.\n\n### Homebrew (alternative)\n\n```bash\nbrew tap theDanButuc/tap\nbrew install --cask claude-usage-monitor\n```\n\n---\n\n## Usage\n\n| Element | Meaning |\n|---------|---------|\n| 🌲 **Green** `45/100` | Plenty of messages left (\u003c 50 % used) |\n| 🌲 **Yellow** `67/100` | Getting there (50 – 80 % used) |\n| 🌲 **Red** `88/100` | Almost out (\u003e 80 % used) |\n| 🌲 **Grey** `⚠ 45/100` | Data is stale (last update \u003e 10 min ago) |\n\n**Left-click** the icon to open the popover:\n\n- **Circular ring** — current session usage percentage\n- **Resets in X h Y m** — time until the next usage window resets\n- **Period total card** — billing-period total (when session data is available separately)\n- **Rate limit badge** — Normal / Limited\n- **Refresh button** (↻) — force an immediate scrape\n- **Quit button** — exit the app\n\n**Right-click** the icon for a quick context menu:\n\n- Current usage and reset countdown at a glance\n- **Refresh Interval** submenu — choose 30s / 1m / 2m / 5m / 10m (persisted across launches)\n- **Refresh Now** — immediate refresh\n- **Quit**\n\n---\n\n## Building from source\n\nYou need **Xcode Command Line Tools** (free) — full Xcode is not required.\n\n```bash\nxcode-select --install   # if not already installed\n```\n\nClone and build:\n\n```bash\ngit clone https://github.com/theDanButuc/Claude-Usage-Monitor.git\ncd Claude-Usage-Monitor\n\nbash scripts/build.sh             # native arch (arm64 or x86_64)\nbash scripts/build.sh --universal # universal binary (arm64 + x86_64)\n```\n\nProduces `dist/ClaudeUsageMonitor-vX.X.X.dmg` ready to install.\n\n### Regenerate the app icon\n\n```bash\nswift scripts/make_icon.swift\n# Produces /tmp/AppIcon.icns — copy to ClaudeUsageMonitor/Assets/AppIcon.icns\n```\n\n### Open in Xcode (optional)\n\n```bash\nbrew install xcodegen\nxcodegen generate          # creates ClaudeUsageMonitor.xcodeproj\nopen ClaudeUsageMonitor.xcodeproj\n```\n\n---\n\n## How it works\n\n### Data source\n\nThe app embeds a hidden `WKWebView` that loads `claude.ai/settings/usage` using your stored browser session (via `WKWebsiteDataStore.default()` — the same cookie store Safari uses for WebKit-based apps).\n\nA JavaScript **fetch/XHR interceptor** is injected at document start, before any page script runs. It captures every API response that mentions usage, limits, or quotas and forwards the raw JSON to Swift. This gives session-window data (e.g. the 5-hour rate-limit window) not visible in the page's DOM text. A DOM-text extraction pass runs 5 s after page load as a fallback.\n\n### Cookie persistence\n\n`WKWebsiteDataStore.default()` persists cookies to disk between app launches automatically — no manual Keychain work needed. If the session expires, the login window reappears.\n\n---\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| \"Cannot be opened because the developer cannot be verified\" | Right-click → Open, or run `xattr -cr /Applications/ClaudeUsageMonitor.app` |\n| Login window keeps appearing | Your Claude session expired — log in again |\n| Shows `0/0` or no numbers | Claude.ai's page changed; open a GitHub Issue with your macOS version |\n| Icon missing from menu bar | Quit via the popover's Quit button and re-open the app |\n| App won't launch after macOS update | Rebuild from source with the updated SDK |\n\n---\n\n## Project structure\n\n```\nClaudeUsageMonitor/\n├── ClaudeUsageMonitor/\n│   ├── ClaudeUsageMonitorApp.swift   # @main entry point\n│   ├── AppDelegate.swift             # Status bar, popover, refresh timer\n│   ├── LoginWindowController.swift   # Full-screen login WebView\n│   ├── Models/\n│   │   └── UsageData.swift           # Data model + computed helpers\n│   ├── Services/\n│   │   ├── WebScrapingService.swift  # WKWebView + JS interceptor\n│   │   ├── NotificationService.swift # Usage threshold \u0026 reset notifications\n│   │   └── UpdateService.swift       # GitHub Releases update check\n│   ├── Views/\n│   │   ├── ContentView.swift         # Popover UI\n│   │   └── CircularProgressView.swift\n│   ├── Assets/\n│   │   └── AppIcon.icns              # All 10 icon sizes\n│   ├── Info.plist\n│   └── ClaudeUsageMonitor.entitlements\n├── scripts/\n│   ├── build.sh                       # Local build + DMG script\n│   └── make_icon.swift               # Icon generator (Swift script)\n├── screenshots/\n│   └── popover.png                   # App screenshot\n├── .github/workflows/\n│   ├── release.yml                   # CI: build \u0026 publish DMG on git tag\n│   └── update-homebrew-tap.yml       # CI: update Homebrew cask after release\n├── project.yml                        # XcodeGen spec\n└── .gitignore\n```\n\n---\n\n## Requirements\n\n- macOS 13 Ventura or later\n- An active Claude.ai account (Free, Pro, Team, or Max)\n- Internet connection\n\n---\n\n## License\n\nMIT — use freely, attribution appreciated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FtheDanButuc%2FClaude-Usage-Monitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FtheDanButuc%2FClaude-Usage-Monitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FtheDanButuc%2FClaude-Usage-Monitor/lists"}