ClaudeMeter Project | Ali Yılmaz

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:

APIService fetches usage data and owns retry and failure handling.
KeychainService reads existing Claude Code credentials securely.
NotificationService manages thresholds and macOS notifications.
PollingManager controls the adaptive refresh lifecycle.
CacheManager persists the last known usage state.
DependencyContainer connects 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

Why it matters

The project turns a recurring CLI check into a low-friction desktop signal. Its value is not simply displaying a percentage; it is the product work around secure credential access, adaptive polling, cache behavior, notification control, and native presentation.