ClaudeBar

🎄✨ Merry Christmas Eve, everyone! ✨🎄

Wishing warmth, joy, and peace to all who celebrate. May your holidays be filled with love and laughter.

Time to slow down, enjoy the magic, and celebrate with the people who matter most.

However you spend tonight - we hope it's filled with joy 🎄

May your code be bug-free, your quotas stay green, and your builds always succeed! 🚀

(P.S. Check ClaudeBar for a snowy surprise ❄️)

Happy Holidays! ❤️🎁

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

    

Dark Mode                                          Light Mode

Christmas Theme

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

Features

• Multi-Provider Support - Monitor Claude, Codex, Gemini, GitHub Copilot, and Antigravity 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
• Seasonal Themes - Festive Christmas theme with snowfall animation, auto-enabled 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

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

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, Antigravity    │
│  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

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