ClaudeBar

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

    

Dark Mode                                          Light Mode

Features

• Multi-Provider Support - Monitor Claude, Codex, Gemini, and GitHub Copilot quotas in one place
• Real-Time Quota Tracking - View Session, Weekly, and Model-specific usage percentages
• Light & Dark Themes - Automatically adapts to your system appearance
• 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

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

# 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"

Architecture

ClaudeBar uses a layered architecture with protocol-based dependency injection:

┌─────────────────────────────────────────────────┐
│                   App Layer                     │
│     SwiftUI Views + @Observable AppState        │
└─────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│                 Domain Layer                    │
│  Models: UsageQuota, UsageSnapshot, QuotaStatus │
│  Protocols: UsageProbe, StatusChangeObserver    │
│  Services: QuotaMonitor (Actor)                 │
└─────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│              Infrastructure Layer               │
│  Probes: Claude, Codex, Gemini, Copilot probes  │
│  Adapters: Pure 3rd-party wrappers (no coverage)│
└─────────────────────────────────────────────────┘

Key Design Decisions

• Rich Domain Models - Business logic lives in domain models, not ViewModels
• Actor-Based Concurrency - Thread-safe state management with Swift actors
• Protocol-Based DI - @Mockable protocols enable testability without real CLI/network
• Adapters Folder - Pure 3rd-party wrappers excluded from code coverage
• No ViewModel Layer - SwiftUI views directly consume domain models

Dependencies

• Sparkle - Auto-update framework
• Mockable - Protocol mocking for tests

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.

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