v1.19.0

Active Account Switch Detection

Previously, switching Claude accounts could leave the app showing stale usage data from the old account until the cached token expired. Now the app actively detects account switches by comparing its cached token against Claude's keychain every 5 minutes.

What's new

• Active keychain sync — periodic subprocess check detects token changes within ~5 minutes
• Immediate UI update — stale usage data is cleared as soon as a switch is detected
• Timeout-safe — subprocess timeouts trigger denial cooldown, preventing recurring macOS keychain dialogs
• Passive 401 fallback — retained as a safety net if the active check is skipped

Upgrade

Download ClaudeCodeUsage.dmg, open it, and drag to Applications (replacing the existing app).

v1.18.0 - Subprocess Keychain Reader & Setup Token

What's New

Subprocess Keychain Reader

Expired tokens are now recovered automatically by reading Claude's keychain via a /usr/bin/security subprocess with a 3-second timeout. If macOS shows an ACL password dialog, the subprocess is killed (SIGTERM) and a 6-hour cooldown prevents retrying — the app falls back to file-based credentials instead of freezing.

Setup Token Support

Run claude setup-token and paste the result in Settings > Authentication. When configured, the app uses this long-lived token exclusively and never touches Claude Code's keychain — eliminating all permission prompts.

Reliability Improvements

• Polling watchdog restarts stalled loops automatically
• Safety valve resets stuck loading states after 45 seconds
• Wake-from-sleep always waits for network before polling
• Update checks run as fire-and-forget (never block the polling loop)
• Debug builds skip update checks to avoid false "update available" prompts

Credential Priority (8-step chain)

1. CLAUDE_USAGE_OAUTH_TOKEN env var
2. Setup token (app's own keychain)
3. In-memory cache
4. App keychain cache
5. Claude keychain via subprocess (automatic, killable)
6. Claude keychain via direct read (user-initiated only)
7. App file cache
8. File credentials

Full Changelog: v1.16.2...v1.18.0

v1.16.2 - Auto-Refresh Fix

Bug Fix

Fixes auto-refresh regression introduced in v1.16.0 where the menu bar percentage would only update when clicking the popover.

What was happening

The account switch detection feature caused auto-refresh to get stuck in needsManualRefresh state because:

1. syncWithSourceIfNeeded() could trigger blocking keychain prompts
2. The refresh logic blocked auto-refresh even when existing cached data was available

What's fixed

• Auto-refresh now works reliably every 60 seconds
• Non-blocking keychain access for account switch detection
• Thread-safety improvements for notification service
• Better handling of debug builds without app bundle

Technical Changes

• Changed refresh blocking condition from || to && - only blocks when BOTH no data AND keychain prompt required
• Created preflightClaudeKeychainAccessWithData() for single non-blocking keychain call
• Added MainActor wrapping for UNUserNotificationCenter calls
• Added bundle identifier guards for running from raw executable

v1.16.1

Bug Fix

• Fixed keychain prompts: Skip keychain verification when in-memory cache is warm, preventing repeated password prompts during account switch detection

The v1.16.0 account switch detection feature could trigger keychain prompts even after clicking "Always Allow" due to macOS ACL inconsistencies. This fix trusts the warm in-memory cache and only verifies against keychain when cache is cold. Account switches are still detected via 401 API response.

v1.16.0 - Automatic Account Switch Detection

What's New

Automatic Account Switch Detection

The app now automatically detects when you switch Claude Code accounts and seamlessly updates to use the new credentials.

How it works:

• On each refresh cycle, the app compares its cached token against Claude's keychain
• If you run claude logout followed by claude login with different credentials, the app detects this within 60 seconds
• All caches are automatically invalidated and new credentials are used
• No manual intervention required

Changes

• Added automatic account switch detection on refresh cycles
• Improved credential priority documentation
• Enhanced cache management for multi-account scenarios

Installation

Download ClaudeCodeUsage.dmg, open it, and drag the app to your Applications folder.

Note: The app requires macOS 14+ and access to Claude Code's keychain entries.

v1.15.1 - API Response Null Handling

Fixed

• JSON decoding failure when API returns null reset times
• App now handles "resets_at": null when 5-hour utilization is 0%
• Fixes "Authentication Required" error that occurred despite valid credentials

Details

The API returns "resets_at": null when utilization is at 0% (e.g., start of a fresh 5-hour window). The decoder expected a non-optional Date, causing the error: "Failed to parse response: The data couldn't be read because it is missing."

This typically occurred around 5-6pm when the 5-hour window resets to 0% utilization.

Technical Changes

• Made resetsAt optional in UsageWindowResponse model
• Provide sensible defaults (5h/7d from now) when resetsAt is null
• Use flatMap for model-specific windows to exclude when no reset time available

Installation

Download ClaudeCodeUsage.dmg, open it, and drag the app to your Applications folder.

v1.15.0

Fix: Stale File Cache Override

Fixes "Authentication Required" errors when the keychain has a valid token but file-based credentials are stale.

What Changed

• Credential priority now prefers keychain over file sources on macOS
• The keychain is the authoritative source (updated by Claude CLI on token refresh)
• File-based sources remain as fallbacks for Linux or when keychain access is denied

New Priority Order

1. Environment variable
2. Memory cache
3. App keychain cache
4. Claude's keychain ← moved up
5. App file cache (fallback)
6. File credentials (fallback)

Upgrade Notes

Existing users: If you had stale cached tokens, the first request may return 401, but the retry will automatically fetch the valid keychain token. No manual intervention needed.

v1.14.0 - File Cache Fallback

What's New

File Cache Fallback - App no longer gets stuck on "Authentication Required" when keychain ACLs break.

The Problem

When code signing changes or the app moves locations, macOS keychain ACLs can break, blocking the app from reading its own cached credentials. Users would see "Authentication Required" even with valid tokens.

The Solution

Added ~/.config/claudecodeusage/oauth-cache.json as a fallback credential cache:

• Immune to keychain ACL issues - File-based, no code signing dependencies
• Self-healing - Any successful credential read populates both keychain AND file
• Secure - File permissions set to 600 (owner read/write only)

New Credential Priority

1. Environment Variable (CLAUDE_USAGE_OAUTH_TOKEN)
2. Memory Cache
3. App Keychain Cache
4. App File Cache (NEW)
5. File Credentials (~/.claude/.credentials.json)
6. Claude's Keychain

---

Full Changelog: v1.13.1...v1.14.0

v1.13.1 - Auto-Refresh Fix

Bug Fixes

Menu Bar Auto-Refresh

Fixed a critical issue where the menu bar percentage would only update when the user clicked it, rather than refreshing automatically every 60 seconds.

Root Cause: Overly conservative credential checks were blocking all automatic refreshes after the initial data fetch, causing the app to get stuck in a "manual refresh required" state.

Solution:

• Auto-refresh logic now only blocks when no cached data exists OR keychain interaction is required
• Allows graceful retry attempts when existing data is present
• Maintains security by preventing keychain prompts during automatic refreshes

Additional Improvements

• Fixed MainActor isolation for the update loop to ensure thread safety
• Added comprehensive debug logging for credential flow diagnostics
• Code reviewed and security validated

Installation

Download ClaudeCodeUsage.dmg, open it, and drag the app to your Applications folder.

What's Changed

Full Changelog: v1.13.0...v1.13.1

v1.13.0 - Menu Bar Fix & Keychain Cooldown Reset

What's New

Bug Fixes

• Fixed menu bar text color - Text now properly uses system color (white on dark menu bars) instead of appearing black
• Fixed hourglass icon appearance - Rate limit icon now adapts to menu bar appearance with isTemplate = true
• Fixed keychain cooldown blocking manual retries - User-initiated refresh now clears the 6-hour denial cooldown, allowing immediate retry instead of being stuck (thanks @paquettej for the fix!)

Improvements

• Modernized SwiftUI APIs (foregroundColor → foregroundStyle)
• Modern number formatting using .formatted() instead of String(format:)

Technical

• Universal binary (Apple Silicon + Intel)
• Code signed and notarized by Apple

---

Full Changelog: v1.12.0...v1.13.0