Claude Usage

A minimal macOS menu bar app that shows your Claude plan limits at a glance — in the menu bar and on the dock icon.

Built with SwiftUI. Designed to feel native to macOS.

       

What it shows

Indicator	Source
32% in menu bar	Current 5-hour session utilization
Current Session	5-hour rolling window — progress + time until reset
Weekly · All Models	7-day cap across Opus + Sonnet — progress + reset
Weekly · Sonnet	7-day Sonnet-only cap — progress + reset

How it works

Calls GET https://api.anthropic.com/api/oauth/usage using your Claude Code OAuth token stored in macOS Keychain (service: "Claude Code-credentials").

No API key to configure. If you're logged into Claude Code, it just works. You can also sign in directly from the app via browser OAuth.

The response provides utilization percentages (0–100) and reset timestamps for each limit window.

Requirements

• macOS 14+ (Sonoma)
• Xcode 15+ (or Swift 5.9 toolchain)
• Claude Code logged in with a Pro or Max plan

Project structure

Sources/
├── App/
│   └── ClaudeUsageApp.swift        # @main entry point + AppDelegate
├── Models/
│   ├── MenuBarDisplayMode.swift     # Menu bar display options
│   └── UsageWindow.swift            # Usage data model
├── Views/
│   ├── DockTileView.swift           # Dock icon percentage overlay
│   └── PopoverView.swift            # Main popover UI
└── Services/
    └── UsageService.swift           # OAuth, API calls, caching
Scripts/
└── generate-icon.swift              # App icon generator

Deploy

Build, install, and launch the app in one step:

./deploy.sh

This will:

1. Kill any running instance
2. Remove the app from the dock
3. Uninstall the previous version from /Applications
4. Build a release binary
5. Generate the app icon and package the .app bundle
6. Code-sign and install to /Applications
7. Add the app to the dock
8. Launch it

Start at login

System Settings → General → Login Items → add Claude Usage

Uninstall

pkill -x ClaudeUsage 2>/dev/null
rm -rf "/Applications/Claude Usage.app"

License

MIT