ClaudeUsage

A sleek macOS menu bar app that shows your Claude subscription usage at a glance.

Lives quietly in your menu bar. No dock icon, no window clutter. One click and you see how much of your Claude limits you've used.

---

Important

Unofficial. Not affiliated with, endorsed by, or supported by Anthropic. It reads the same usage endpoint the Claude website uses, authenticated with your own session.

---

✨ Features

🧭 Menu bar app	Always a click away — no dock icon, no separate window.
📊 Live percentage	Your current 5-hour session usage, right in the menu bar.
🎯 Detail popover	5-hour session and 7-day weekly limits with colored bars and reset times.
🔐 Built-in sign-in	Log in to Claude in an embedded browser — no manual token copying.
🔒 Secure storage	Session key stored encrypted in the macOS Keychain, never in plain text.
⚡ Auto-refresh	Updates every 5 minutes, or instantly with the refresh button.
🌍 English / German	Switch the interface language in Settings (default: English).

---

📦 Requirements

• 🖥️ macOS 13 (Ventura) or newer
• 👤 An active Claude subscription (Pro / Max)
• 🛠️ Xcode 15 or newer — only if you build from source

---

🚀 Installation

⬇️ Download (easiest)

1. Go to the latest release and download ClaudeUsage.zip.
2. Unzip it and drag ClaudeUsage.app into your Applications folder.
3. On first launch, right-click the app → "Open" and confirm. (Required because the app is not notarized by Apple. You only need to do it once.)

🔨 Build from source (for developers)

git clone https://github.com/alirezasalehfar/ClaudeUsage.git
cd ClaudeUsage

1. Open ClaudeUsage.xcodeproj in Xcode.
2. Under Signing & Capabilities, select your Team (a free Apple account is enough for local use).
3. Make sure App Sandbox → Outgoing Connections (Client) is enabled.
4. Press ⌘R to build and run — the icon appears in your menu bar.

🔁 Launch at login

System Settings → General → Login Items → "Open at Login" → add ClaudeUsage.app with +.

---

🔧 Setup

👤 Signing in

1. Click the menu bar item and open the gear ⚙️ (Settings).
2. Choose Sign in to Claude….
3. Log in to claude.ai in the window that appears. The app reads your session automatically and closes the window.
4. Your 5-hour and 7-day usage now appear in the popover.

To sign out, open Settings and choose Sign out of Claude.

Note

Your session key is stored locally in the macOS Keychain and is never part of the source code — safe to push to a public repo. The app talks only to claude.ai; there is no telemetry and no third-party server.

Warning

Anthropic offers no public API for subscription usage, so the app uses the same internal endpoint the web UI relies on. Because it is internal, it may change at any time and temporarily break the app.

---

📖 Usage

1. Click the menu bar icon — the current 5-hour percentage is shown there.
2. The popover shows two cards: Current session (5 h) and This week (7 days), each with a colored bar and reset time.
3. Hit the refresh ↻ button for an instant update (otherwise it refreshes every 5 minutes).
4. Open the gear ⚙️ to switch language or sign out.

Bar colors: 🟢 under 70 % · 🟠 70–90 % · 🔴 above 90 %.

---

🧱 Tech overview

• 🎨 SwiftUI with MenuBarExtra (window style) plus separate Window scenes for Settings and Login
• 🌐 WKWebView login that reads the sessionKey cookie via WKHTTPCookieStore (works even though the cookie is HttpOnly)
• 🔒 Keychain (Security framework) for the encrypted session key
• 📡 URLSession against claude.ai/api/organizations/{id}/usage, with browser-like headers to pass Cloudflare
• 🌍 Lightweight custom EN/DE localization driven by a @Published language switch

---

📝 Notes

• The app is locally self-signed. On first launch, right-click → Open if Gatekeeper complains.
• The session key expires after a while — just sign in again when the app reports it.
• When signed out, the popover shows a hint to sign in via Settings.

---

Made with SwiftUI · Runs on your Mac 🖥️