ClaudeMeter is a native macOS menu bar utility for monitoring Claude Code usage without repeatedly returning to the terminal. It keeps the five-hour and seven-day usage windows, reset times, and warning thresholds visible in a compact desktop interface.
The problem
Claude Code is centered on terminal workflows, but usage limits are easy to lose sight of during long sessions or while moving between several tasks. Checking them manually interrupts the current context and makes it harder to plan intensive work near a reset boundary.
The goal was to make this information continuously available while preserving a quiet, native macOS experience.
Product goals
- Keep the most important usage windows one click away in the menu bar
- Show reset times and plan-specific limits in a readable format
- Warn at useful thresholds without producing repeated notifications
- Preserve the last known state during temporary connectivity problems
- Remain lightweight and avoid unnecessary desktop complexity
Main capabilities
Usage visibility
The application supports icon, compact, and detailed display modes. It tracks the five-hour and seven-day windows, provides Opus-specific visibility, and presents reset times directly in the menu bar interface.
Notifications
System notifications can be enabled for 75%, 90%, and 95% usage thresholds. A throttling layer prevents the same state from generating noisy repeated alerts.
Refresh and offline behavior
Polling adapts to activity rather than running at a single aggressive interval. A cache preserves the last successful response, allowing the interface to remain useful during a temporary network failure.
Architecture
ClaudeMeter is implemented as a SwiftUI menu bar application with explicit service boundaries:
APIServicefetches usage data and owns retry and failure handling.KeychainServicereads existing Claude Code credentials securely.NotificationServicemanages thresholds and macOS notifications.PollingManagercontrols the adaptive refresh lifecycle.CacheManagerpersists the last known usage state.DependencyContainerconnects these services without coupling them to views.
This separation keeps credentials, networking, cache state, polling, and presentation independently understandable and testable.
Installation
The application targets macOS 13 Ventura or later and can be installed from a GitHub release or built with Xcode 15+.
git clone https://github.com/puq-ai/claude-meter.git
cd claude-meter
xcodebuild -scheme ClaudeMeter -configuration Release build
ClaudeMeter uses the existing Claude Code session, so the CLI authentication flow must be completed first:
claude login
Links
Engineering notes
Although ClaudeMeter is a small menu bar utility, it coordinates several independent concerns: data refresh, offline state, Keychain access, and notification frequency. Separating the interface from the service layer keeps those behaviors visible, testable, and easier to change independently.