Claude Usage

A macOS menu bar app that shows your Claude plan usage at a glance. It sits in your menu bar and shows your 5-hour and 7-day utilization percentages so you always know where you stand before hitting rate limits.

Screenshots

  

What it does

• Menu bar indicator — shows your current 5h/7d usage as percentages right in the menu bar. Icon changes when you're getting close to limits.
• Dashboard popup — click to see a full breakdown: plan usage bars, session stats, daily activity chart, token usage by model, hourly heatmap, and model breakdown.
• Desktop widgets — toggle floating widgets for plan usage, stats, or activity charts directly on your desktop. Drag them wherever you want.
• Local stats — reads from ~/.claude/stats-cache.json to show session counts, message history, and token breakdowns.
• Launch at login — optional, toggle it from the settings section in the dashboard.

How it works

The app pulls your plan usage from the Anthropic API using the OAuth token that Claude Code stores in your macOS Keychain. No API keys to configure — if you're logged into Claude Code, it just works.

Local usage stats (sessions, messages, tokens) come from ~/.claude/stats-cache.json, which gets updated as you use Claude Code. The app watches the file for changes and updates in real time.

Requirements

• macOS 14 (Sonoma) or later
• Claude Code installed and logged in (for plan usage data)

Build & Run

cd ClaudeUsageMenu
make run

That builds a release binary, bundles it into ClaudeUsageMenu.app with the icon and Info.plist, and opens it.

Other make targets:

make build    # just compile
make bundle   # compile + create .app bundle
make clean    # remove build artifacts

Project structure

ClaudeUsageMenu/
├── Sources/ClaudeUsageMenu/
│   ├── App/                  # App entry point, menu bar label
│   ├── Models/               # Data models (plan usage, stats)
│   ├── Services/             # API loader, file watcher, widget manager
│   ├── Theme/                # Colors, spacing, shared design tokens
│   └── Views/
│       ├── Cards/            # Dashboard cards (plan usage, charts, heatmap, etc.)
│       ├── Widgets/          # Floating desktop widget views
│       └── DashboardView.swift
├── SupportFiles/             # Info.plist, app icon
├── Package.swift
└── Makefile

Notes

• The OAuth token is read from Keychain at runtime, nothing is stored or hardcoded.
• Plan usage refreshes every 60 seconds automatically.
• The app uses SwiftUI Charts for all the visualizations.
• Built as a pure Swift Package Manager project, no Xcode project file needed.