Claude Usage Monitor

한국어

A lightweight macOS menu bar app that shows your Claude (claude.ai) usage in real time.

Install

Step 1. Download

Homebrew (Recommended)

brew tap Dann1y/tap
brew install --cask claude-usage-monitor

Or manually

git clone https://github.com/Dann1y/claude-usage-monitor.git
cd claude-usage-monitor
make install

Step 2. Allow app to run

Since this app is not notarized with Apple, macOS will block it on first launch. Run this once:

xattr -cr "/Applications/Claude Usage Monitor.app"

Then open the app. It appears in your menu bar — enable Launch at login in Settings to keep it running permanently.

Update

The app checks for new versions automatically every 24 hours and shows a notification badge when an update is available.

Homebrew

brew upgrade --cask claude-usage-monitor

If brew upgrade doesn't detect new versions, run this once to fix it:

git -C "$(brew --repository dann1y/tap)" config homebrew.forceautoupdate true

Or manually

cd claude-usage-monitor
git pull
make install

Uninstall

brew uninstall claude-usage-monitor
# or
make uninstall

How It Works

1. Reads your Claude Code OAuth token from the macOS Keychain (Claude Code-credentials) — usage data from claude.ai/Desktop/CLI is all aggregated server-side, so any Claude Code session counts
2. Fetches usage data from the Anthropic API on-demand when you open the popover, with a background refresh every 30 minutes
3. Auto-refreshes the OAuth token when it expires using the stored refresh token, so you don't need to keep claude running in a terminal — the Keychain entry is updated atomically (security add-generic-password -U) so the CLI stays logged in
4. Caches usage data locally so the app stays responsive even when the API is unavailable

No API keys or manual configuration required! — it uses the same credentials that Claude Code CLI stores automatically.

Features

• Live usage percentage in the menu bar with color-coded icon (green / orange / red)
• 5-hour sliding window utilization with reset countdown
• 7-day weekly utilization with per-model breakdown (Opus, Sonnet)
• On-demand refresh when opening the popover (30s cooldown)
• Background polling every 30 minutes to stay up-to-date
• Automatic OAuth token refresh — works even if you only use Claude Desktop and never open a terminal
• Local disk cache for persistent data across app restarts
• Launch at login support
• Automatic update notifications via GitHub Releases (checks every 24h)

Prerequisites

• macOS 14.0 (Sonoma) or later
• Claude Code CLI — run claude at least once to store OAuth credentials in your macOS Keychain

License

MIT