jaywedgeworth22/codecaps

CodeCaps

一个 macOS 菜单栏应用，读取你 Mac 上已有的 AI 编程 CLI 配额，并在你掌控的一组机器之间推送和拉取这些配额。

下载 CodeCaps →

为什么会有这个项目

CodeCaps 读取这台 Mac 上已经登录的 AI 编程 CLI 的配额——全程无需输入任何提供商的 API 密钥——并可以将这些读数推送到你自己运行的服务器，再把该服务器聚合的读数拉取回来，这样一个 Glance 弹出面板就能同时显示不止一台机器的配额。

对于单台 Mac，已经有更好的工具了。steipete/CodexBar（MIT，69 个提供商，已签名并公证）和 tddworks/ClaudeBar（MIT，20+ 个提供商，已签名并公证）都覆盖了 CodeCaps 支持的每一个提供商，而且走得更远。如果你只关心眼前这台机器，请改用它们中的一个。

CodeCaps 存在的理由，是这两者都不处理的事情：把配额推送到你自己的端点，并把一整组机器的配额拉取回同一个视图中。

它显示什么

CodeCaps 有两个界面。两者不会同时渲染任何内容。

Glance 是菜单栏弹出面板——两秒钟的快速查看。每个平台一行，分组在 This Mac 和 Fleet 之下，每行带有百分比、使用条和重置倒计时。除了 Refresh、Settings 和 Open CodeCaps 之外，它是只读的。

Console 是一个可调整大小的窗口，侧边栏分为 Quotas 和 Settings：Quotas 是全平台概览，外加带搜索的按平台下钻视图；Settings 包含下面五个页面。

一个平台的头条数字是如何选出的

一个平台可能带有不止一个配额窗口，因此每个界面都有自己的规则来决定哪个数字领衔：

- 折叠行（Glance，或 Console 卡片）显示最接近上限的新鲜窗口——剩余百分比最低——并带有该窗口自己的重置倒计时。
- 菜单栏有自己的选择器（Menu Bar → Displayed Quota）：Lowest active quota（默认，高于 0% 中的最低百分比）、Lowest quota（绝对最低百分比，包含零），或按名称固定某一个窗口。
- Console 的 Next Reset 磁贴是所有平台上每个新鲜窗口中最早的重置时间——不限于哪个窗口接近上限。

Antigravity 销售两个独立的模型池，显示为两行：Gemini 和 Claude & GPT。过去折叠它们时，一旦 Claude/GPT 每周上限用尽，就会显示“Antigravity 0%”，而 Gemini 仍有大部分额度。每当某个池的每周窗口归零时，它的 5 小时百分比就会被隐去——显示为 n/a，而不是一个在本周重置之前毫无意义的数字。

提供商

| 提供商 | 读取内容 | 来源 |
|---|---|---|
| Claude | 配额窗口（5 小时、每周） | ~/.claude/.credentials.json，或 Claude Code-credentials 钥匙串项 |
| Codex | 速率限制窗口 | ~/.codex/auth.json |
| Antigravity / Gemini | 合并的 Gemini 和 Claude & GPT 配额，两行（见上图） | antigravity-usage CLI，外加对 Antigravity 自身语言服务器的 RPC |
| Cursor | 包含套餐的使用量 | Cursor.app 的本地会话数据库（state.vscdb） |
| Grok CLI | 账单/额度，通过 Grok 的 CLI 代理 | ~/.grok/auth.json |
| Grok Bot | 每周使用量，通过 Cursor 的仪表盘服务 | 同一个 Cursor 会话数据库，不同的端点 |
| MiniMax | 按模型和每周剩余配额 | ~/.mmx/config.json |
| DeepSeek | 不支持 | 基于余额，而非基于窗口。没有本地读取器；拉取的窗口也会被过滤掉——绝不会在任何地方出现。 |

以上任何一项都从不要求手动输入凭据——每个读取器都复用 CLI 已创建的会话或文件。

当新安装的 CodeCaps 首次需要 Claude Code 的钥匙串项时，macOS 会询问是否允许其通过：登录钥匙串按应用授予访问权限，而新安装的 CodeCaps 对它来说是一个新应用，因此即使 Claude Code 已登录，Claude 也可能显示为已登出。打开 Console → Settings → Sources & Fleet，在 Claude 行上按 Allow Access To Claude Code，并在 macOS 弹出的面板中选择 Always Allow——它只会询问一次，这是一次读取，CodeCaps 绝不会写入或删除 Claude Code 保存的登录信息。

集群推送与拉取

两者默认关闭，在 Console → Settings → Sources & Fleet 中配置。

推送格式——两种，推送时选择。生产者 id 为 codecaps（保留 agent-bar 作为可识别的旧版别名，以实现无缝向后兼容）。

usage_monitor_v2——每个配额窗口一个事件：

{
"schemaVersion": 2,
"producerId": "codecaps",
"producerInstanceId": "Jay's MacBook Pro",
"events": [
{
"eventId": "subq:anthropic:5h-window:2026-09-17T14:00:00Z:2026-09-17T14:41:00Z",
"provider": "anthropic",
"service": "codecaps",
"label": "5h",
"metricType": "quota",
"billingMode": "actual",
"confidence": "actual",
"limit": 100,
"credits": 62.0,
"occurredAt": "2026-09-17T14:41:00Z",
"metadata": {
"bucketId": "5h-window",
"isExhausted": false,
"remainingUnknown": false,
"scale": "percent_0_100",
"source": "codecaps",
"usedPercent": 38.0
},
"tier": "Max 20x"
}
]
}

generic_webhook——一个更简单的信封：

{
"format": "codecaps-quotas",
"version": 1,
"generatedAt": "2026-09-17T14:41:00Z",
"machine": "Jay's MacBook Pro",
"count": 1,
"windows": [
{
"id": "anthropic:5h",
"provider": "anthropic",
"label": "5h",
"status": "available",
"isExhausted": false,
"remainingPercent": 62.0,
"resetAt": "2026-09-17T17:53:00Z",
"window": "5h",
"plan": "Max 20x",
"occurredAt": "2026-09-17T14:41:00Z"
}
]
}

拉取（Pull）。 CodeCaps 将服务器聚合后的窗口（generatedAt、windows[]、可选的 providerGroups[]）读回为 Fleet 行。一个窗口通过其携带的 source/sourceApp 归属到某台机器——目前尚不存在机器标识符字段，因此无法区分的 Mac 会显示为同一个 fleet 来源。

端点规则。 任何主机都要求 HTTPS；仅回环地址（localhost、127.0.0.1、::1）允许使用明文 HTTP。带有内嵌凭据、查询字符串或片段（fragment）的 URL 会被拒绝。

令牌存储。 Ingest Token 和 Read Token 是仅有的两个被存储的密钥，二者都存放在 macOS 钥匙串（Keychain）中，而非配置文件中。

BotFleet 本地交接

独立于任何服务器，CodeCaps 会将一份不含凭据的本地快照写入：

~/Library/Application Support/Usage Monitor/quota-windows.json

供其他本地消费者使用（例如 BotFleet 的 Usage Monitor）。format 为 usage-monitor-local-quotas，version 为 1，同时包含 producer（"codecaps"）、generatedAt、一个 windows 数组以及可选的 issues 映射——不含服务器 URL、账户标识符或令牌；错误字符串会先经过检查，确保其中不含任何凭据形态的内容。以 0600 权限写入 0700 目录内，并通过原子重命名完成。

安装

Homebrew

brew install --cask jaywedgeworth22/tap/codecaps

下载

从最新发布版获取已签名并公证的 CodeCaps.dmg。

从源码构建

要求：macOS 14+、Apple 芯片或 Intel、带有 Swift 5.9+ 工具链的 Xcode Command Line Tools。

git clone https://github.com/jaywedgeworth22/codecaps.git
cd codecaps
script/build_and_run.sh            # build, install to ~/Applications, and relaunch

其他模式：--install（相同，但不重新启动）；--dev（将单独的 .dev 标识符构建到 dist/，与已安装副本并排启动；--dev-stop 会退出它并删除 dist/）；--package（通用 Release，压缩为 zip 并附带 SHA-256 文件放入 dist/）；--release（先 --package，然后对 app 进行公证并装订（staple），再构建、签名、公证并装订 dist/CodeCaps.dmg）；--build-only（仅暂存 dist/CodeCaps.app）。

--package 和 --release 会为 Apple 芯片和 Intel 构建一个通用二进制文件，并用 lipo -archs 进行验证。CFBundleShortVersionString 来自仓库根目录的 VERSION 文件，因此发布新版本只需一次编辑，而 CFBundleVersion 是提交计数。--release 通过由 AGENTBAR_NOTARY_PROFILE 命名的钥匙串配置文件进行公证（默认值为 agentbar-notary），该配置文件需使用 xcrun notarytool store-credentials 创建一次。
run 和 --install 只保留一份已安装副本，位于 ~/Applications/CodeCaps.app：任何其他具有相同 release identifier 的 bundle，无论是在常见安装位置还是此 checkout 的 dist/ 中，都会被移到废纸篓并打印出来，包括仍然名为 AgentBar.app 的副本。CODECAPS_PRUNE_DRY_RUN=1 会预览而不移动任何内容；CODECAPS_BUNDLE_ID 会在不同的 identifier 下构建，以支持多个 checkout。

签名仍在演进中——请将其视为当前最佳实践，而非固定契约。脚本会在可用时使用 Developer ID Application 身份进行签名（AGENTBAR_CODESIGN_IDENTITY，或你钥匙串中已有的第一个），如果找不到或签名超时，则回退到 ad-hoc（codesign --sign -）。这不仅仅关乎 Gatekeeper：稳定的身份能让保存的 token（Sources & Fleet）在重新构建后仍可读取；而 ad-hoc 下，每次构建都会获得新身份，因此保存的 token 之后需要 Re-Authorize Saved Token。

Gatekeeper。 没有稳定身份时——--dev 始终如此——macOS 会阻止首次启动；请右键并选择 Open，或执行 xattr -d com.apple.quarantine。--package 会为公证签名，但到此为止；--release 才是真正提交给 Apple 并 stapling ticket 的模式，这也是已发布的 dmg 打开时完全没有任何警告的原因。

图标。 assets/ 中的母版是一个全出血方形，并保持如此。macOS 26 之前不会对 app 图标进行遮罩，因此 script/make_icon.swift 会在构建时派生 macOS 形状——将母版绘制在 1024 画布上的 824x824 圆角矩形内，并带有标准投影——.icns 由此构建。母版文件只会被读取。

设置

Console 的侧边栏有五个设置页面。

- 菜单栏 — 图标显示位置（菜单栏、Dock 或两者），以及其 Displayed Quota 选择器（上方）。
- 平台 — 平台列表顺序，由 Glance、Console 和菜单栏共享。
- Sources & Fleet — 三组：This Mac（读取器开/关，每个平台一行状态）、Share This Mac（推送：Ingest Endpoint、Ingest Token、Payload Format、Save & Push Now）、Pull The Fleet（拉取：Quota Endpoint、Read Token、Save & Fetch Now）。两个 fleet 组还提供 Forget Token，并且仅在保存的 token 无法读回时，提供 Re-Authorize Saved Token。
- 外观 — 浅色、深色或系统；系统跟随你的 Mac 设置，且为默认。
- 关于 — 版本、推送/拉取/本地读取器状态，以及项目页面链接。

隐私

- 从不要求提供 provider API key；每个 CLI 自己的凭据文件、Keychain 项或会话数据库都会按原样复用。
- 在你开启推送或拉取并自行输入 endpoint 之前，任何内容都不会离开这台 Mac；字段默认为空。
- Ingest Token 和 Read Token 是仅有的两个被存储的密钥，二者都存储在 Keychain 中。
- 端点按上述方式验证（HTTPS、仅回环 HTTP、无内嵌凭据/查询/片段）。
- 本地交接文件仅携带配额读数——不包含令牌、端点或账户标识符。

提供商标记

每个标记都是模板图像——仅使用其轮廓，并根据标签着色。claude.svg、openai.svg、grok.svg、minimax.svg 和 gemini.svg 是 BotFleet 自有资产（受其源许可证约束）；Antigravity 复用 Gemini 标记，Grok CLI/Grok Bot 复用 Grok 标记。cursor.svg 来自 Simple Icons，CC0 1.0；详情见 Sources/CodeCaps/Resources/ProviderMarks/README.md。

开发

swift build
swift test

当同时从多个检出构建时，请参见上文的 AGENTBAR_BUNDLE_ID。

日志

构建和公证输出写入 $TMPDIR/CodeCaps-build-.log（每次运行一个）。应用本身默认不记录到文件——菜单/弹出框诊断请查看 Console.app → “CodeCaps”，更深入的内容请使用 log show --process CodeCaps --last 1h。

许可证

Apache License 2.0。

商标

提供商名称和标记归其所有者所有，仅用于标识相关服务。