ClaudeBar

A macOS menu bar application that monitors AI coding assistant usage quotas. Keep track of your Claude, Codex, Gemini, GitHub Copilot, Antigravity, and Z.ai usage at a glance.

    

Dark Mode                                          Light Mode

CLI Theme

Minimalistic monochrome terminal aesthetic with classic green accents

Christmas Theme

Festive holiday theme with snowfall animation - automatically enabled during the Christmas season!

Features

• Multi-Provider Support - Monitor Claude, Codex, Gemini, GitHub Copilot, Antigravity, and Z.ai quotas in one place
• Provider Enable/Disable - Toggle individual providers on/off from Settings to customize your monitoring
• Real-Time Quota Tracking - View Session, Weekly, and Model-specific usage percentages
• Multiple Themes - Light, Dark, CLI (terminal-style), and festive Christmas themes
• Automatic Adaptation - System theme follows your macOS appearance; Christmas auto-enables during the holiday season
• Visual Status Indicators - Color-coded progress bars (green/yellow/red) show quota health
• System Notifications - Get alerted when quota status changes to warning or critical
• Auto-Refresh - Automatically updates quotas at configurable intervals
• Keyboard Shortcuts - Quick access with ⌘D (Dashboard) and ⌘R (Refresh)

Quota Status Thresholds

Remaining	Status	Color
> 50%	Healthy	Green
20-50%	Warning	Yellow
< 20%	Critical	Red
0%	Depleted	Gray

Requirements

• macOS 15+
• Swift 6.2+
• CLI tools installed for providers you want to monitor:
  • Claude CLI (claude)
  • Codex CLI (codex)
  • Gemini CLI (gemini)
  • GitHub Copilot - Configure credentials in Settings
  • Antigravity - Auto-detected when running locally
  • Z.ai - Configure Claude Code with GLM Coding Plan endpoint

Installation

Download (Recommended)

Download the latest release from GitHub Releases:

• DMG: Open and drag ClaudeBar.app to Applications
• ZIP: Unzip and move ClaudeBar.app to Applications

Both are code-signed and notarized for Gatekeeper.

Build from Source

git clone https://github.com/tddworks/ClaudeBar.git
cd ClaudeBar
swift build -c release

Usage

swift run ClaudeBar

The app will appear in your menu bar. Click to view quota details for each provider.

Development

Command Line (Swift Package Manager)

# Build the project
swift build

# Run all tests
swift test

# Run tests with coverage
swift test --enable-code-coverage

# Run a specific test
swift test --filter "QuotaMonitorTests"

Xcode (with SwiftUI Previews)

The project uses Tuist to generate Xcode projects with ENABLE_DEBUG_DYLIB for SwiftUI previews.

# Install Tuist (if not installed)
brew install tuist

# Generate Xcode project
tuist generate

# Open in Xcode
open ClaudeBar.xcworkspace

After opening in Xcode, SwiftUI previews will work with Cmd+Option+Return.

Architecture

Full documentation: docs/ARCHITECTURE.md

ClaudeBar uses a layered architecture with QuotaMonitor as the single source of truth:

Layer	Purpose
App	SwiftUI views consuming domain directly (no ViewModel)
Domain	Rich models, QuotaMonitor, repository protocols
Infrastructure	Probes, storage implementations, adapters

Key Design Decisions

• Single Source of Truth - QuotaMonitor owns all provider state
• Repository Pattern - Settings and credentials abstracted behind injectable protocols
• Protocol-Based DI - @Mockable protocols enable testability
• Chicago School TDD - Tests verify state changes, not method calls
• No ViewModel/AppState - Views consume domain directly

Contributing

Adding a New AI Provider

Use the add-provider skill to guide you through adding new providers with TDD:

Tell Claude Code: "I want to add a new provider for [ProviderName]"

The skill guides you through: Parsing Tests → Probe Tests → Implementation → Registration.

See .claude/skills/add-provider/SKILL.md for details and AntigravityUsageProbe as a reference implementation.

Dependencies

• Sparkle - Auto-update framework
• Mockable - Protocol mocking for tests
• Tuist - Xcode project generation (for SwiftUI previews)

Releasing

Releases are automated via GitHub Actions. Push a version tag to create a new release.

For detailed setup instructions, see docs/RELEASE_SETUP.md.

Release Workflow

The workflow uses Tuist to generate the Xcode project:

Tag v1.0.0 → Update Info.plist → tuist generate → xcodebuild → Sign & Notarize → GitHub Release

Version is set in Sources/App/Info.plist and flows through to Sparkle auto-updates.

Quick Start

1. Configure GitHub Secrets (see full guide):

   Secret	Description
   APPLE_CERTIFICATE_P12	Developer ID certificate (base64)
   APPLE_CERTIFICATE_PASSWORD	Password for .p12
   APP_STORE_CONNECT_API_KEY_P8	API key (base64)
   APP_STORE_CONNECT_KEY_ID	Key ID
   APP_STORE_CONNECT_ISSUER_ID	Issuer ID

2. Verify your certificate:

   ./scripts/verify-p12.sh /path/to/certificate.p12

3. Create a release:

   git tag v1.0.0
   git push origin v1.0.0

The workflow will automatically build, sign, notarize, and publish to GitHub Releases.

License

MIT