ClaudeUsage

A lightweight macOS menu bar app that shows your Claude Code plan usage at a glance.

---

ClaudeUsage lives in your menu bar and polls the same usage endpoint the Claude Code CLI uses, so you can see how close you are to your 5-hour and weekly limits without leaving what you're doing. No separate login: it reads the OAuth token that the Claude Code CLI already stored in your macOS Keychain.

Features

• Menu bar bar showing your current 5-hour usage at a glance, with an optional percentage readout
• Click-to-open panel with daily, weekly, and pay-as-you-go extra-credit usage
• Countdown to when each limit resets
• Animated menu bar icon (togglable)
• No accounts, no servers, no telemetry: it talks only to api.anthropic.com using your existing local Claude Code credentials

Requirements

• macOS 13 (Ventura) or later
• Claude Code CLI installed and logged in (claude; this is what puts the OAuth token in your Keychain)
• Xcode Command Line Tools (for swift build)

Installation

There's no signed release yet, so build it from source:

git clone https://github.com/<your-username>/claude-checker.git
cd claude-checker
Scripts/setup_signing_identity.sh   # one-time: creates a local code-signing identity
Scripts/build_app.sh                # builds and assembles build/ClaudeUsage.app
open build/ClaudeUsage.app

Drag build/ClaudeUsage.app into /Applications if you want it to stick around, or run Scripts/build_dmg.sh to produce a .dmg installer instead.

The first time it reads your Keychain, macOS will prompt you to allow access, choose Always Allow. setup_signing_identity.sh creates a stable local signing certificate specifically so that this prompt only happens once, even across rebuilds (see Why the custom signing identity below).

Usage

Click the bar in the menu bar to open the usage panel. It refreshes automatically every 2 minutes, or click refresh to force an update. The gear icon opens settings for the menu bar's percentage text and animated icon.

How it works

• Auth: reads the "Claude Code-credentials" item from your login Keychain (the same one the claude CLI writes to); ClaudeUsage never asks for or stores your credentials itself.
• Data: polls https://api.anthropic.com/api/oauth/usage with your existing OAuth token.
• Rendering: the menu bar label is a single hand-drawn bitmap (not a stack of SwiftUI views), which is what keeps the icon/bar/text from being mis-measured by the status item.

Why the custom signing identity

A self-signed certificate can never carry a TeamIdentifier, and the Keychain item's partition list is restricted by team ID. Signing with an ad-hoc or throwaway certificate means macOS re-prompts for your login password on every single rebuild. Scripts/setup_signing_identity.sh creates one stable local certificate so Always Allow persists across rebuilds instead.

Development

This is a plain Swift Package Manager executable; there's no Xcode project. swift build alone produces a binary but not a runnable .app bundle (no Info.plist, no LSUIElement, so it'd show a Dock icon and no proper menu bar identity); use Scripts/build_app.sh for that.

Command	Purpose
swift build	Fast compile check (debug), doesn't produce a runnable .app
Scripts/build_app.sh	Full release build, icon generation, bundle assembly, code signing
Scripts/build_dmg.sh	Builds the app (if needed) and packages it into a .dmg
Scripts/setup_signing_identity.sh	One-time: creates the local signing certificate

Typical dev loop:

swift build                                    # catch compile errors fast
Scripts/build_app.sh                           # produce a runnable .app
pkill -x ClaudeUsage; open build/ClaudeUsage.app  # relaunch and see the change

There's no test suite.

Project structure

Sources/ClaudeUsage/       App source
  ClaudeUsageApp.swift       App entry point (MenuBarExtra scene)
  MenuBarView.swift          Menu bar label + usage panel UI
  UsageService.swift         Polls the usage API
  KeychainManager.swift      Reads the OAuth token from Keychain
  AppSettings.swift          Persisted user toggles
  Models.swift                Codable API/Keychain models
  Resources/                 Bundled runtime assets (idle animation)
Resources/Info.plist       Bundle metadata (identifier, LSUIElement, ...)
Scripts/                   Build, packaging, and signing scripts
Assets/                    Unbundled source art (icon/animation originals)

Contributing

Issues and pull requests are welcome. If you're changing UI behavior, please build and click through the actual .app (Scripts/build_app.sh) rather than just relying on swift build: the menu bar rendering has some non-obvious constraints documented in CLAUDE.md.

Disclaimer

This is an unofficial, community-built tool. It is not affiliated with or endorsed by Anthropic.