ClaudeUsageBar

A native macOS menu bar app that shows your Claude Code usage at a glance. Click the gauge in the menu bar to open a popup with:

• Plan limit rings — live 5-hour session and weekly utilization percentages (the same numbers Claude Code's /usage command shows), with reset countdowns.
• Cost & tokens — today / this week / this month, computed locally from your Claude Code transcripts (ccusage-compatible parsing and dedup).
• Active session — current 5-hour billing block: time remaining, cost so far, burn rate, and projected end-of-block cost.
• 14-day chart + model breakdown — stacked daily cost per model family (Opus / Sonnet / Haiku) with consistent colors throughout.

The menu bar label shows your 5-hour utilization (e.g. 42%) when plan data is available, or today's cost otherwise. Fully dark-mode aware, no Dock icon.

Requirements

• macOS 13 (Ventura) or newer
• Xcode 15+ command line tools (xcode-select --install)
• Claude Code installed and used at least once (transcripts in ~/.claude or ~/.config/claude; set CLAUDE_CONFIG_DIR if yours live elsewhere)

Build & run

cd ClaudeUsageBar

# 1. Run the unit tests (data layer: parsing, pricing, session blocks)
swift test

# 2. Quick smoke test — runs directly, menu bar icon appears
swift build && .build/debug/ClaudeUsageBar

# 3. Build the real app bundle (release build, no Dock icon, ad-hoc signed)
./Scripts/make-app.sh
open build/ClaudeUsageBar.app

To start it at login: System Settings → General → Login Items → + → select build/ClaudeUsageBar.app.

Keychain access (for the plan limit rings)

Plan-limit percentages come from Anthropic's OAuth usage endpoint, using the credentials Claude Code stores in your Keychain (Claude Code-credentials). On first launch macOS will ask whether ClaudeUsageBar may read that item — click Always Allow. If you deny it, everything else keeps working; only the rings show a locked placeholder.

Credential lookup order: Keychain → ~/.claude/.credentials.json → CLAUDE_CODE_OAUTH_TOKEN env var. The app never refreshes or writes tokens — Claude Code owns those; if your token has expired, just run any Claude Code command and the rings recover on the next poll (every 3 minutes).

How it computes things

• Transcripts: parses projects/**/*.jsonl under your Claude config dirs, keeping only assistant turns with usage data. Duplicate request snapshots are deduplicated by messageId:requestId, keeping the latest snapshot (it carries the final output token count). Files are cached by mtime/size and re-read incrementally, so refreshes stay cheap even with large histories.
• Cost: uses the transcript's costUSD when present, otherwise computes from tokens using the pricing table in Sources/ClaudeUsageBar/Data/PricingTable.swift (rates dated in a comment — update them there when Anthropic's pricing changes). Unknown models cost $0 and are marked with ≈.
• 5-hour blocks: ccusage-compatible — blocks start at the top of the hour of the first message and last 5 hours; a gap of more than 5 hours starts a new block. When live plan data is available, the API's reset time drives the countdown and the local block supplies cost/burn-rate.