https://github.com/tddworks/ClaudeBar
A macOS menu bar application that monitors AI coding assistant usage quotas. Keep track of your Claude, Codex, and Gemini usage at a glance.
https://github.com/tddworks/ClaudeBar
Last synced: 4 months ago
JSON representation
A macOS menu bar application that monitors AI coding assistant usage quotas. Keep track of your Claude, Codex, and Gemini usage at a glance.
- Host: GitHub
- URL: https://github.com/tddworks/ClaudeBar
- Owner: tddworks
- Created: 2025-12-20T13:58:06.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-12-26T04:16:30.000Z (4 months ago)
- Last Synced: 2025-12-26T04:24:19.450Z (4 months ago)
- Language: Swift
- Homepage: https://tddworks.github.io/ClaudeBar/
- Size: 38 MB
- Stars: 221
- Watchers: 2
- Forks: 19
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
- awesome-swift-macos-apps - ClaudeBar - commit/tddworks/ClaudeBar?style=flat&label=" /> - Real-time monitoring of usage quotas for various AI coding assistants. (Menubar / Text)
- awesome-github-projects - ClaudeBar - A macOS menu bar application that monitors AI coding assistant usage quotas. Keep track of your Claude, Codex, Antigravity ,and Gemini usage at a glance. ⭐1,064 `Swift` 🔥 (🤖 AI & Machine Learning)
README
# ClaudeBar
[](https://github.com/tddworks/ClaudeBar/actions/workflows/build.yml)
[](https://github.com/tddworks/ClaudeBar/actions/workflows/tests.yml)
[](https://codecov.io/gh/tddworks/ClaudeBar)
[](https://github.com/tddworks/ClaudeBar/releases/latest)
[](https://swift.org)
[](https://developer.apple.com)
> 🎄✨ **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, Antigravity, and Z.ai 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, Antigravity, and Z.ai 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](https://claude.ai/code) (`claude`)
- [Codex CLI](https://github.com/openai/codex) (`codex`)
- [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini`)
- [GitHub Copilot](https://github.com/features/copilot) - Configure credentials in Settings
- [Antigravity](https://antigravity.google) - Auto-detected when running locally
- [Z.ai](https://z.ai/subscribe) - Configure Claude Code with GLM Coding Plan endpoint
## Installation
### Download (Recommended)
Download the latest release from [GitHub Releases](https://github.com/tddworks/ClaudeBar/releases/latest):
- **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
```bash
git clone https://github.com/tddworks/ClaudeBar.git
cd ClaudeBar
swift build -c release
```
## Usage
```bash
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)
```bash
# 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](https://tuist.io) to generate Xcode projects with `ENABLE_DEBUG_DYLIB` for SwiftUI previews.
```bash
# 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, Z.ai │
│ 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](https://sparkle-project.org/) - Auto-update framework
- [Mockable](https://github.com/Kolos65/Mockable) - Protocol mocking for tests
- [Tuist](https://tuist.io) - 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](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](docs/RELEASE_SETUP.md)):
| 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**:
```bash
./scripts/verify-p12.sh /path/to/certificate.p12
```
3. **Create a release**:
```bash
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