A lightweight Apple ecosystem app that shows your Claude API usage limits in real time. Runs as a menu bar app on macOS, includes a macOS widget, and ships as a full app with home screen widgets on iOS.
| macOS Menu Bar | macOS & iOS Widget |
|---|---|
 |
 |
- Session utilization (5-hour rolling window) and weekly utilization (7-day rolling window)
- Optional per-model breakdowns (Opus / Sonnet) when available
- Color-coded tiers for quick scanning: green (< 50%), yellow (50-79%), red (>= 80%)
- Auto-refreshes every 5 minutes, plus manual refresh
- macOS: menu bar extra with gauge icon and percentage, plus a WidgetKit desktop widget
- iOS: full app + WidgetKit home screen widget (small and medium sizes)
- In-app OAuth login (PKCE) — independent of any Claude Code installation
- Xcode 15+ with Swift toolchain
- macOS 14+ (menu bar app) or iOS 15+ (mobile app)
- A Claude account (Pro, Team, or Enterprise) with API access
git clone https://github.com/gabreho/claude-usage.git
cd claude-usage
open ClaudeUsage.xcodeprojIn Xcode:
- Select a scheme: ClaudeUsage (macOS) or ClaudeUsageiOS (iOS)
- Choose a destination: My Mac or an iOS Simulator
- Press Run (Cmd+R)
The app needs an OAuth access token to call https://api.anthropic.com/api/oauth/usage. On first launch it shows a sign-in button. Tapping it opens an in-app browser where you sign in with your Claude account. The app handles the full OAuth PKCE flow and stores credentials in its own Keychain entry — completely independent of any Claude Code installation.
claude-usage/
├── ClaudeUsage.xcodeproj # Xcode project (all targets)
├── ClaudeUsageKit/ # Shared Swift package
│ └── Sources/ClaudeUsageKit/
│ ├── UsageService.swift # API client + credential management
│ ├── UsageModels.swift # Data models + tier logic
│ ├── KeychainService.swift # Keychain read/write
│ ├── OAuthTokenClient.swift # Token exchange and refresh
│ ├── PKCEUtility.swift # PKCE code challenge generation
│ ├── UsageDashboardView.swift # Main dashboard UI
│ ├── UsageMetricsView.swift # Usage metric rows
│ └── UsageWidgetSharedStore.swift # Widget data sharing
├── ClaudeUsageMacWidget/ # macOS widget extension config files
├── Sources/
│ ├── ClaudeUsage/ # macOS menu bar app
│ ├── ClaudeUsageiOS/ # iOS app
│ ├── ClaudeUsageWidget/ # Shared WidgetKit implementation (iOS + macOS)
│ └── Shared/ # Cross-platform views
└── docs/
└── ios-token-strategy.md # iOS auth decision record
The app calls Anthropic's OAuth usage endpoint with a bearer token and displays the returned utilization percentages. On macOS, a MenuBarExtra scene renders a gauge icon and label in the system menu bar, and a WidgetKit extension surfaces the same usage data on the desktop. On iOS, the same data feeds both the main app and a WidgetKit timeline.
The app stores credentials in its own Keychain entry (claude-usage-credentials) and automatically refreshes tokens before they expire. It never reads from or writes to Claude Code's Keychain entries.
- OAuth Client ID: The app currently uses Claude Code's public OAuth client ID because Anthropic doesn't yet offer third-party client registration. This may change in the future.
- No automated tests: The project doesn't include unit or integration tests yet. Contributions welcome.
- iOS widget refresh: iOS limits widget updates to roughly every 15 minutes — this is an OS-level constraint, not an app limitation.
- Per-device authentication: Each device authenticates independently. There's no iCloud Keychain sync between devices.
# macOS
xcodebuild -project ClaudeUsage.xcodeproj \
-scheme ClaudeUsage \
-configuration Debug \
build
# iOS (simulator)
xcodebuild -project ClaudeUsage.xcodeproj \
-scheme ClaudeUsageiOS \
-configuration Debug \
-destination 'platform=iOS Simulator,name=iPhone 16' \
build- Show time remaining until usage reset alongside the percentage
- Track Extra usage metrics (current spend, monthly limit, balance)
- Threshold notifications when approaching usage limits
- Dedicated settings service for managing preferences
MIT