richhickson/claudecodeusage

macOS menu bar app showing Claude Code usage limits (session/weekly/per-model/overage) with alerts and click-to-focus when a Claude Code session needs your attention

Claude Usage – macOS menubar helper for Anthropic Claude Code

What it is – A tiny native‑Swift macOS app that lives in the menu bar and shows you, in real time, how much of your Claude Code quota you’ve consumed. It also notifies you when a Claude Code session is waiting for your input, letting you jump straight to the terminal tab where the session is running.

Why it matters – Claude Code (the CLI for Anthropic’s Claude model) enforces per‑session, weekly and monthly usage caps. Keeping an eye on those limits helps you avoid unexpected overage charges and prevents sessions from silently stalling.

Core features

Feature	What you get
Usage tracking	Shows current session usage, weekly caps (including model‑specific caps like Fable/Opus), and monthly overage spend. Colours (green < 70 %, yellow ≥ 70 %, red ≥ 90 %) give an instant health check.
Auto‑refresh	Queries Anthropic’s usage endpoint every 5 minutes, retries on network or key‑chain hiccups, and refreshes on wake‑from‑sleep.
Session alerts (opt‑in)	A bell icon with a count appears when a Claude Code session needs your permission or input. macOS notifications can be toggled, and clicking a notification or the list entry jumps to the exact Terminal/iTerm2 tab.
Live session list	In the pop‑over you see each tracked session’s state: needs you 🔔, working ⚙️, or finished ✅.
Claude Code settings editor	From the app you can edit the global `CLAUDE.md` file and adjust the `cleanupPeriodDays` that controls how long local transcripts are kept.
Convenience	Launch‑at‑login toggle, built‑in update checker, and a lightweight footprint (native Swift, no extra runtimes).

How it works under the hood

Credentials – The app reads your Claude Code OAuth token from the macOS Keychain (no password ever leaves the machine).
Usage data – It calls the undocumented Anthropic endpoint api.anthropic.com/api/oauth/usage to fetch quota information.
Session monitoring – When you enable alerts, the app writes a tiny POSIX‑sh hook into ~/.claude/settings.json. Claude Code runs this hook for each session, writing JSON status files to ~/.claude/claudeusage/. The menubar app watches that directory and updates the UI/notifications accordingly.
Click‑to‑focus – macOS accessibility permissions let the app tell Terminal/iTerm2 to select the tab that matches the session ID, so you can respond instantly.

Installation & getting started

Download – Grab the latest ClaudeUsage.zip from the Releases page, unzip, and drag ClaudeUsage.app into Applications.
First launch – Right‑click → Open the first time (macOS will warn about an unsigned app). The app will automatically locate your Claude Code credentials.
Optional – build from source – Clone the repo, open ClaudeUsage.xcodeproj in Xcode, then ⌘B to build and ⌘R to run.
Enable alerts – Click the gear icon in the menu‑bar pop‑over, toggle Alert when a session needs attention. The app will install/remove the hook in ~/.claude/settings.json for you.

Requirements

macOS 13 (Ventura) or newer
Claude Code CLI installed (npm i -g @anthropic-ai/claude-code) and logged in (claude)

Privacy & licensing

No telemetry; the only network call is to Anthropic’s official usage API.
MIT‑licensed source – you can audit or modify it freely.
Unofficial tool – not affiliated with Anthropic; it relies on an undocumented API that could change.

Made by @richhickson