tddworks/ClaudeBar
GitHub: tddworks/ClaudeBar
一款 macOS 菜单栏应用，集中监控 Claude、Codex、Gemini 等多种 AI 编程助手的使用配额和消耗状态。
Stars: 1382 | Forks: 120
# 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)
[](https://formulae.brew.sh/cask/claudebar)
一款用于监控 AI 编程助手使用配额的 macOS 菜单栏应用。帮助您一目了然地掌握 Claude、Codex、Gemini、GitHub Copilot、Antigravity、Z.ai、Kimi、Kiro、Amp、OpenCode Go、Oh My Pi、Grok 等多种工具的使用情况。
## 功能
- **多服务商支持** - 在同一处集中监控 Claude、Codex、Gemini、GitHub Copilot、Antigravity、Z.ai、Kimi、Kiro、Amp、OpenCode Go、Oh My Pi 和 Grok 的配额
- **服务商启用/禁用** - 在“设置”中单独切换各个服务商的开启或关闭状态，自定义您的监控范围
- **实时配额追踪** - 查看 Session、Weekly 以及特定模型的使用百分比
- **多种主题** - 包含浅色、深色、CLI、圣诞节主题以及[导入的终端主题](#import-terminal-theme) (.itermcolors)
- **自动适配** - 系统主题自动跟随您的 macOS 外观设置；圣诞节主题会在节日期间自动启用
- **可视化状态指示** - 颜色编码的进度条（绿/黄/红）直观展示配额健康状态
- **系统通知** - 当配额状态变为警告或危险时接收提醒
- **自动刷新** - 按照可配置的时间间隔自动更新配额
- **键盘快捷键** - 使用 `⌘D` (Dashboard) 和 `⌘R` (刷新) 快速访问
## 配额状态阈值
| 剩余量 | 状态 | 颜色 |
|-----------|--------|-------|
| > 50% | 健康 | 绿色 |
| 20-50% | 警告 | 黄色 |
| < 20% | 危险 | 红色 |
| 0% | 耗尽 | 灰色 |
## 环境要求
- macOS 15+
- Swift 6.2+
- 针对您想要监控的服务商，需安装相应的 CLI 工具：
- [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) - 在“设置”中配置凭证
- [Antigravity](https://antigravity.google) - 在本地运行时自动检测
- [Z.ai](https://z.ai/subscribe) - 使用 GLM Coding Plan endpoint 配置 Claude Code
- [Kimi](https://www.kimi.com/code/console) (`kimi`) - CLI 模式（推荐）或 API 模式（见下文）
- [Kiro](https://kiro.dev) (`kiro-cli`) - 需要安装 kiro-cli（见下文）
- [Amp](https://ampcode.com) (`amp`) - 安装 CLI 后自动检测
- [OpenCode Go](https://opencode.ai/go) (`opencode`) - 通过本地 SQLite 数据库追踪 OpenCode Go 使用窗口 (5小时/$12、每周/$30、每月/$60)
- [Oh My Pi](https://omp.sh) (`omp`) - 通过 `omp usage --json` 汇总账户使用情况，显示 rate-limit 窗口，并在有报告时显示有上限的美元充值卡或无上限的消耗提示
- [Grok Build](https://docs.x.ai) (`grok`) - 使用 CLI 的本地 OAuth 凭证追踪 xAI credit 使用情况（每周窗口 + 单个产品的 Grok Build / Imagine / Voice 限制）
### Kimi 配置
Kimi 支持两种探测模式，可以在 **设置 > Kimi 配置** 中进行配置：
**CLI 模式（推荐）** - 启动交互式 `kimi` CLI 并发送 `/usage` 指令以获取配额数据。需要安装 `kimi` CLI (`uv tool install kimi-cli`)。无需“完全磁盘访问权限”。
**API 模式** - 使用浏览器 cookie 身份验证直接调用 Kimi API。需要授予 ClaudeBar **“完全磁盘访问权限”**以读取 `kimi-auth` 浏览器 cookie：
1. 打开 **系统设置** > **隐私与安全性** > **完全磁盘访问权限**
2. 开启 **ClaudeBar** 的开关（或点击 `+` 并添加它）
3. 重启 ClaudeBar
您还可以设置 `KIMI_AUTH_TOKEN` 环境变量，以在 API 模式下免去读取 cookie 的步骤。
### Kiro 配置
Kiro 通过 `kiro-cli` 命令行工具监控 AWS Kiro（前身为 CodeWhisperer）的使用情况。
**安装**：`uv tool install kiro-cli` 或 `pip install kiro-cli`
**身份验证**：运行 `kiro-cli` 并按照提示登录。
**Kiro IDE 用户**：如果您使用的是 Kiro IDE，只需安装 kiro-cli 即可。两者共享相同的身份验证，因此无需额外登录。
## 安装说明
### Homebrew
通过 [Homebrew](https://brew.sh) 安装。
```
brew install --cask claudebar
```
### 下载（推荐）
从 [GitHub Releases](https://github.com/tddworks/ClaudeBar/releases/latest) 下载最新版本：
- **DMG**：打开并将 ClaudeBar.app 拖入“应用程序”
- **ZIP**：解压并将 ClaudeBar.app 移至“应用程序”
两者均已进行代码签名并经过公证，可顺利通过 Gatekeeper。
### 从源码构建
```
git clone https://github.com/tddworks/ClaudeBar.git
cd ClaudeBar
# 安装 Tuist（如果尚未安装）
brew install tuist
# 安装依赖并构建
tuist install
tuist build ClaudeBar -C Release
```
## 使用说明
构建完成后，打开生成的 Xcode workspace 并运行应用：
```
tuist generate
open ClaudeBar.xcworkspace
```
然后在 Xcode 中按下 `Cmd+R` 运行。该应用将显示在您的菜单栏中。点击即可查看各个服务商的配额详情。
## 开发指南
本项目使用 [Tuist](https://tuist.io) 进行依赖管理和 Xcode 项目生成。
### 快速开始
```
# 安装 Tuist（如果尚未安装）
brew install tuist
# 安装依赖
tuist install
# 生成 Xcode 项目并打开
tuist generate
open ClaudeBar.xcworkspace
```
### 构建与测试
```
# 构建项目
tuist build
# 运行所有测试
tuist test
# 运行测试并生成覆盖率报告
tuist test --result-bundle-path TestResults.xcresult -- -enableCodeCoverage YES
# 构建 release configuration
tuist build ClaudeBar -C Release
```
### SwiftUI Previews
在 Xcode 中打开项目后，可以通过 `Cmd+Option+Return` 使用 SwiftUI 预览。项目已配置了 `ENABLE_DEBUG_DYLIB` 以支持预览功能。
## 架构
ClaudeBar 采用**分层架构**，以 `QuotaMonitor` 作为单一数据源：
| 层级 | 用途 |
|-------|---------|
| **App** | 直接使用领域层的 SwiftUI 视图（无 ViewModel） |
| **Domain** | 富模型、`QuotaMonitor`、repository 协议 |
| **Infrastructure** | 探测器、存储实现、适配器 |
### 关键设计决策
- **单一数据源** - `QuotaMonitor` 持有所有服务商的状态
- **Repository 模式** - 设置和凭证通过可注入的协议进行抽象
- **基于协议的依赖注入 (DI)** - `@Mockable` 协议提升了可测试性
- **芝加哥学派 TDD** - 测试用于验证状态变化，而非方法调用
- **无 ViewModel/AppState** - 视图直接消费领域层
## 导入终端主题
让 ClaudeBar 的外观与您的终端保持一致。支持导入任何 `.itermcolors` 文件：
1. 打开 **设置**（齿轮图标）
2. 点击 **导入 .itermcolors**
3. 选择您的文件（从 iTerm2 导出：Preferences > Profiles > Colors > Color Presets > Export）
在 [iTerm2-Color-Schemes](https://github.com/mbadolato/iTerm2-Color-Schemes/tree/master/schemes) 获取 450+ 预设配色方案。
导入的主题会保存在 `~/.claudebar/themes/` 目录下，并在重启后依然保留。
## 贡献指南
### 添加新的 AI 服务商
使用 **add-provider** 技能引导您通过 TDD 添加新的服务商：
```
Tell Claude Code: "I want to add a new provider for [ProviderName]"
```
该技能会引导您完成：解析测试 → 探测器测试 → 实现 → 注册。
详情请查阅 `.claude/skills/add-provider/SKILL.md`，并参考 `AntigravityUsageProbe` 的实现。
## 依赖项
- [Sparkle](https://sparkle-project.org/) - 自动更新框架
- [Mockable](https://github.com/Kolos65/Mockable) - 用于测试的协议模拟工具
- [Tuist](https://tuist.io) - Xcode 项目生成（用于 SwiftUI 预览）
## 发布
发布过程通过 GitHub Actions 自动化。只需推送版本 tag 即可创建新版本。
**详细的配置说明，请参见 [docs/release/RELEASE_SETUP.md](docs/release/RELEASE_SETUP.md)。**
### 发布工作流
该工作流使用 Tuist 生成 Xcode 项目：
```
Tag v1.0.0 → Update Info.plist → tuist generate → xcodebuild → Sign & Notarize → GitHub Release
```
版本号在 `Sources/App/Info.plist` 中设置，并会同步传递给 Sparkle 自动更新。
### 快速开始
1. **配置 GitHub Secrets**（参见[完整指南](docs/release/RELEASE_SETUP.md)）：
| Secret | 描述 |
|--------|-------------|
| `APPLE_CERTIFICATE_P12` | Developer ID 证书 (base64) |
| `APPLE_CERTIFICATE_PASSWORD` | .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. **验证您的证书**：
./scripts/verify-p12.sh /path/to/certificate.p12
3. **创建发布**：
git tag v1.0.0
git push origin v1.0.0
工作流将自动完成构建、签名、公证，并发布到 GitHub Releases。
## 贡献者
感谢所有为 ClaudeBar 做出贡献的人！
 Dark Mode |
 Light Mode |
 CLI Theme |
 Christmas Theme |
标签：AI编程助手, Swift, 使用量监控, 桌面工具, 菜单栏应用