v1.13 — Menu bar appearance settings

What's New

Your menu bar, your call. New Menu Bar Appearance section in settings:

• 🎨 Three styles: Native — a monochrome template icon that matches the rest of your menu bar, with the number turning orange/red only when a limit runs hot; Tinted — the icon colored green/yellow/red by usage level; Emoji — the classic 🟢 look
• 📊 Pick your metric: session %, weekly %, model %, spend, or icon only
• 🔔 Smarter alerts: when a session needs you, the menu bar shows the project's name (e.g. 🔔 gravelship · 27%) so you know which one without clicking — a count when several are waiting. In Native/Tinted styles an orange bell appears alongside your style icon rather than replacing it
• 🧹 Settings window rebuilt as a native grouped form

Existing installs keep the emoji look until you choose otherwise — nothing changes under you on update. Fresh installs default to Native.

Thanks to @kbsooo for pioneering the custom-icon direction in #12 and @ManiForoughi2 for the feedback that shaped this.

Install

Existing users: click Update to v1.13 & Relaunch in the app. New users: download ClaudeUsage.zip, unzip, move to Applications. Signed and notarized.

🤖 Generated with Claude Code

v1.12 — One-click in-app updates

What's New

Updates are now one click. When a new version is available, the popover shows an "Update to vX & Relaunch" button — click it and ClaudeUsage downloads the release, verifies it, installs it, and relaunches itself. No more download-unzip-drag.

Safety details:

• The downloaded update's code signature is verified and must match this app's Developer ID team — anything unsigned or signed by someone else is refused
• The swap rolls back automatically if installation fails, and any error falls back to a manual download link

This is the last version you'll install by hand. 🎉

Install

Download ClaudeUsage.zip, unzip, and move ClaudeUsage.app to Applications. Signed and notarized with Developer ID.

🤖 Generated with Claude Code

v1.11 — Claude status page alerts

What's New

Get notified when Claude has an outage — and when it recovers. ClaudeUsage now checks status.claude.com every 5 minutes:

• 🔴 Notification on any status change — degraded service, partial/major outage, or back to operational. Clicking it opens the status page
• 🟢 Status line in the popover with a severity dot (green / yellow / orange / red), linking to status.claude.com
• ⚙️ Toggle in settings — "Alert when Claude status changes" (on by default)

Install

Download ClaudeUsage.zip, unzip, and move ClaudeUsage.app to Applications. Signed and notarized with Developer ID.

🤖 Generated with Claude Code

v1.10.3 — Click-to-focus actually switches windows

Fixed

Clicking a session now actually switches to its terminal window. The focus AppleScript was being executed via NSAppleScript on a background thread, which silently does nothing — so clicks appeared dead and macOS never even showed the "ClaudeUsage wants to control Terminal" permission prompt. The app now runs the script through an osascript subprocess, which is thread-safe and non-blocking, and logs any failure to ~/.claude/claudeusage/focus-debug.log.

On first click after updating, macOS will ask "ClaudeUsage" wants access to control "Terminal" — click Allow. After that, clicking any session in the popover (or a notification banner) jumps straight to its exact Terminal/iTerm2 window and tab.

Install

Download ClaudeUsage.zip, unzip, and move ClaudeUsage.app to Applications. Signed and notarized with Developer ID.

🤖 Generated with Claude Code

v1.10.2 — Alerts clear when you visit the session

Fixed

The 🔔 alert now clears when you jump to the session. Previously the bell stayed lit after you clicked through to a waiting session, and only cleared once you typed something in that Claude Code window. Clicking a notification banner or a session row now acknowledges the alert: the bell count drops immediately and the session shows as 🔕 "Waiting (seen)" until real activity (a prompt, tool use, or the turn finishing) refreshes its state. A new attention event from the same session re-alerts as normal.

Install

Download ClaudeUsage.zip, unzip, and move ClaudeUsage.app to Applications. Signed and notarized with Developer ID.

🤖 Generated with Claude Code

v1.10.1 — Click-to-focus fix

Fixed

Click-to-focus now jumps to the correct terminal tab. In v1.10, clicking a session (in the popover or a notification) only brought up your most recently used terminal window. The hook script recorded an empty tty because Claude Code runs hooks without a controlling terminal — it now walks up the process tree to the claude process to capture the real tty, so Terminal/iTerm2 tab matching works as intended.

The app auto-updates the installed hook script on launch — no need to re-toggle session alerts. Sessions report their tty on their next event (prompt, tool use, or finish), so give an existing session one interaction before expecting an exact tab jump.

Install

Download ClaudeUsage.zip, unzip, and move ClaudeUsage.app to Applications. Signed and notarized with Developer ID.

🤖 Generated with Claude Code

v1.10 — Session alerts with click-to-focus

What's New

Session alerts (AgentBar-style)

Know when a Claude Code session needs you, without watching the terminal:

• Opt-in toggle in settings installs lightweight Claude Code hooks (pure POSIX sh, no dependencies) that track each session's status
• Menu bar bell — 🔔2 prefix when two sessions are waiting for your permission or input
• macOS notifications when a session needs attention, with the project name and reason — includes a pop-up on/off toggle, permission status display, and a test button
• Live session list in the popover: needs you 🔔 / working ⚙️ / finished ✅
• Click to jump back — click a notification banner or a session row to focus the exact Terminal/iTerm2 tab running that session (VS Code supported at app level)

Hooks preserve all your existing settings.json keys and custom hooks, and are cleanly removed when you toggle off. Sessions started before enabling won't report until restarted/resumed.

Tip: if you use macOS Focus modes, add ClaudeUsage to the Focus allowed apps to receive banners while focused.

Install

Download ClaudeUsage.zip, unzip, and move ClaudeUsage.app to Applications. Signed and notarized with Developer ID.

🤖 Generated with Claude Code

v1.9 — Fable usage tracking & Claude Code settings

What's New

Fable usage tracking

• New usage row for model-specific weekly limits (e.g. Fable), parsed from the API's limits array
• Model limits are included in the menu bar traffic-light status (🟢/🟡/🔴)
• Future model-scoped limits (Opus, Sonnet, etc.) will appear automatically

Claude Code settings editor

New gear icon in the popover opens a settings window where you can:

• Edit your global CLAUDE.md (~/.claude/CLAUDE.md) — tell Claude Code how you like to work, applied across all projects
• Set conversation retention — control how long Claude Code keeps local conversation transcripts (cleanupPeriodDays in ~/.claude/settings.json); saves preserve all your other settings

Install

Download ClaudeUsage.zip, unzip, and move ClaudeUsage.app to Applications. Signed and notarized with Developer ID.

🤖 Generated with Claude Code

v1.8 - Fix 429 API Error + Overage Tracking

What's New

Bug Fixes

• Fix 429 API Error — The Anthropic API now requires a claude-code/* User-Agent header. The app detects your installed Claude Code version and uses it automatically.
• Restored anthropic-beta header required by the usage API
• Retry with exponential backoff on 429/5xx errors (up to 5 retries)
• Updated API response parsing for renamed fields (seven_day_sonnet)

New Features

• Overage tracking — Shows your extra usage spend and monthly limit (e.g. $0.00 of $20 limit) with a progress bar

Changes

• Poll interval increased from 2 to 5 minutes to reduce API load

Install

Download ClaudeUsage.zip, unzip, and move ClaudeUsage.app to Applications. The app is signed and notarized.

v1.7

v1.7 Release Notes

Changes

• Switched to security CLI for keychain access (avoids permission prompts)
• Added fallback to alternate "Claude Code" keychain entry
• Removed first-launch explanation dialog
• Added boot delay - waits for keychain to be ready after system startup
• Auto-updates menu bar reactively via Combine
• Improved error messages with debugging info
• Better retry logic for keychain errors after wake/boot