Claude Usage Bar

A lightweight, native macOS menu bar app that shows your claude.ai usage limits at a glance — your 5-hour session window and your 7-day weekly window — without leaving the menu bar.

Two small Swift binaries compiled with swiftc — no Electron, no Python, no third-party runtime, only Apple frameworks.

Important

Unofficial. This is a community project, not affiliated with or endorsed by Anthropic. It reads the same private endpoint the claude.ai usage page uses, authenticated with your own session cookie. Use at your own discretion.

---

Features

• ✳️ A spark icon in the menu bar showing your current session usage % once a cookie is set.
• 🎨 The menu bar icon and percentage adapt to the menu bar background (white on a dark bar, black on a light one) and are never tinted by usage level.
• 📊 A click-to-open popover with three sections:
  • Current Session — 5-hour window, with a progress bar and reset time.
  • All Models — 7-day weekly window, with a progress bar and reset time.
  • Daily Routines — session resets so far today and time until the next reset.
• 🟡🔴 In the popover, the percentage and progress bars are color-coded: green below 80%, yellow at 80%, red at 90%.
• ⌨️ Global hotkey ⌘U toggles the popover from anywhere.
• 🔄 Refreshes automatically every 5 minutes, when you open the popover, and via the Refresh button.
• 🔐 Your cookie is stored only in the macOS Keychain — never in a file or UserDefaults.
• 🚀 Appears when the Claude desktop app launches and quits when you quit Claude (you can also open or quit it manually).
• 🗑️ Built-in uninstaller (Settings → Uninstall app).

---

Requirements

Everything below ships with macOS or is a one-line install — no Homebrew or extra packages required.

Requirement	Notes
macOS 12 Monterey or later	Apple Silicon or Intel.
Xcode Command Line Tools	Provides swiftc to compile the app. Install with xcode-select --install.
A claude.ai account	Free, Pro, or Max. You paste your session cookie once (see below).
openssl + security	Both ship with macOS. The installer uses them to create a local self-signed certificate so the app has a stable identity and the Keychain stops re-prompting.
(optional) Claude desktop app	If installed, the menu bar app appears when you open Claude and quits when you quit it. Not required — you can launch it manually.

---

Install

git clone https://github.com/tmatteozzi/claude-usage-bar.git
cd claude-usage-bar/app
./install.sh

install.sh does everything in one run:

1. Compiles ClaudeUsageBar.app and the ClaudeLauncher helper with swiftc (deployment target macOS 12).
2. Creates a local self-signed code-signing certificate (ClaudeUsageBar Self-Signed) if one doesn't exist yet, and signs both binaries with it.
3. Copies both to ~/Applications/.
4. Writes the LaunchAgent to ~/Library/LaunchAgents/ and loads it.

After it finishes, open the Claude desktop app (or launch ~/Applications/ClaudeUsageBar.app directly) and the spark appears in your menu bar within a few seconds.

---

First run — set your cookie

The app reads https://claude.ai/api/organizations/{org}/usage using your session cookie (the organization id is resolved automatically from the cookie, falling back to GET /api/organizations). The response is utilization percentages and reset times — claude.ai does not expose raw token counts here. To provide the cookie:

1. Open claude.ai/settings/usage in your browser.
2. Open DevTools (⌘⌥I) → the Network tab → reload the page.
3. Filter by usage and click that request.
4. Under Request Headers, copy the full value of the Cookie header.
5. In the app: left-click the spark → Configure Cookie… → Paste → Save.

The cookie is stored only in your macOS Keychain. It must include sessionKey (and usually lastActiveOrg). Cookies expire periodically — when usage stops updating, paste a fresh one the same way.

---

Controls

Action	Result
Left-click the icon	Open the usage popover
Right-click (or control-click) the icon	Menu: View usage / Quit
⌘U	Toggle the popover from any app
Popover → Refresh	Fetch fresh data now
Popover → Settings	Reconfigure Cookie… or Uninstall app

---

How it works

.
├── README.md
├── LICENSE
├── .gitignore
├── app/
│   ├── ClaudeUsageBar.swift   Main app: status item, popover (SwiftUI), usage fetch,
│   │                          Keychain, ⌘U hotkey (Carbon)
│   ├── ClaudeLauncher.swift   Background agent: launches the menu bar app when the
│   │                          Claude desktop app starts
│   ├── Info.plist             App bundle metadata (LSUIElement = menu-bar-only)
│   ├── SparkIcon.svg          Source icon
│   ├── SparkIcon.pdf          Vector icon bundled into the app (tints to the menu bar color)
│   ├── build.sh               Compiles + signs both binaries into app/build/
│   └── install.sh             build.sh + install to ~/Applications + LaunchAgent
└── LaunchAgents/
    └── com.claudeusagebar.launcher.plist   RunAtLoad + KeepAlive launcher agent

At login, only the silent launcher runs (no icon). When the Claude desktop app launches, the launcher starts the menu bar app; when you quit Claude, the menu bar app quits too.

---

Privacy & security

• Your cookie lives only in the macOS Keychain, under a generic-password item. It is never written to disk, UserDefaults, logs, or anywhere else.
• The app talks only to claude.ai, sending your cookie exactly as your browser would, to read your own usage. No analytics, no telemetry, no other network calls.
• The self-signed certificate the installer creates is local to your machine and is used only to give the app a stable identity so the Keychain stops re-prompting. The uninstaller removes it.

---

Updating

Pull the latest code and re-run the installer — it reuses the existing certificate, so there are no new Keychain prompts:

git pull
cd app && ./install.sh

---

Uninstall

From the app: left-click the spark → Settings → Uninstall app. This removes the app, the launcher, the LaunchAgent, the stored cookie, and the signing certificate.

To do it manually:

launchctl unload ~/Library/LaunchAgents/com.claudeusagebar.launcher.plist
rm ~/Library/LaunchAgents/com.claudeusagebar.launcher.plist
rm -rf ~/Applications/ClaudeUsageBar.app ~/Applications/ClaudeLauncher
security delete-generic-password -s com.claudeusagebar.cookie -a claude-session-cookie
security delete-identity -c "ClaudeUsageBar Self-Signed"

---

Troubleshooting

• The icon shows no percentage / "No usage data". Your cookie is missing or expired. Re-paste it (Configure Cookie…). When the cookie is rejected the popover shows an Unauthorized (HTTP 401/403) hint.
• swiftc: command not found. Install the Xcode Command Line Tools: xcode-select --install.
• The build fails creating the signing certificate. Make sure your login Keychain is unlocked, then re-run ./install.sh. The installer signs the binaries with that certificate.
• No menu bar icon after install. Open the Claude desktop app (the launcher waits for it), or launch ~/Applications/ClaudeUsageBar.app directly. The launcher logs to /tmp/com.claudeusagebar.launcher.err.log.

---

Limitations

• Uses the private claude.ai usage endpoint (the one the website itself calls). It is not an official, documented API and may change without notice.
• The endpoint reports utilization percentages and reset times, not raw token counts — so the UI shows percentages.

---

License

Released under the MIT License — see LICENSE.

---

Claude, Anthropic, and the Claude logo are trademarks of Anthropic. This project is independent and unofficial.