Claude Usage MenuBar

A native macOS menu bar app that shows Claude Code usage in two rolling windows: 5-hour and 7-day.

Reads server-calculated utilization directly from the Anthropic OAuth Usage API — no token counting, no estimates.

How It Works

1. Reads OAuth credentials from macOS Keychain (Claude Code-credentials, written by Claude Code on login)
2. Calls GET https://api.anthropic.com/api/oauth/usage every 60 seconds
3. Displays server-returned utilization % and reset countdown in the menu bar

Credentials are cached in memory — Keychain is accessed only once per session (or after token expiry).

For a detailed explanation of what the app reads from Keychain and what it does with the token, see docs/guide-keychain-access.md.

Prerequisites

• macOS 14 or later

• Claude Code installed and logged in (provides the OAuth token)

• Xcode Command Line Tools or Xcode.app

  xcode-select --install

Getting Started

Build and debug

1. Get the repository root.

   REPOSITORY_ROOT=$(git rev-parse --show-toplevel)
   cd $REPOSITORY_ROOT

2. Run the app in debug mode (CLI only — no menu bar icon).

   DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift run

Build and install

1. Get the repository root.

   REPOSITORY_ROOT=$(git rev-parse --show-toplevel)
   cd $REPOSITORY_ROOT

2. Build the .app bundle.

   ./scripts/make_app_bundle.sh

   This creates ./dist/ClaudeUsageMenuBar.app.

3. Install the app.

   • User-only (recommended):

     cp -R "./dist/ClaudeUsageMenuBar.app" "$HOME/Applications/"

   • System-wide:

     sudo cp -R "./dist/ClaudeUsageMenuBar.app" "/Applications/"

4. Launch the app once so macOS registers it.

Enable auto-start on login

1. Open System Settings → General → Login Items.
2. Under Open at Login, click +.
3. Select ClaudeUsageMenuBar.app from /Applications or ~/Applications.

Note: If the app does not appear in the picker, open ~/Applications in Finder and drag ClaudeUsageMenuBar.app directly into the Open at Login list.

Usage

The menu bar title shows current 5h utilization: ( ᐛ )σ 42.5%

Click the icon to open the popover:

5h  ████████░░ 42.5%
  Resets in: 2h 34m

7d  ██░░░░░░░░ 18.3%
  Resets in: 4d 12h

Burn rate: +0.3%/min

• Refresh — fetch immediately
• Quit — exit the app