QuotaCard

一个常驻 macOS 桌面的小卡片，实时显示 Claude 与 Codex 的额度（5 小时 / 7 天窗口剩余）。 A lightweight macOS desktop widget that shows your Claude & Codex usage limits at a glance.

纯 Swift + AppKit，单文件、无第三方框架；数据由随附的独立 Python 脚本在本机抓取。不上传任何数据，只读你本机已有的浏览器登录态和本地日志。

桌面卡片

右键设置菜单

特性

• 两个服务并排：Claude（左）/ Codex（右），各显示 5h（🕐）与 7d（📅）两个窗口
• 动态油量表：指针随剩余百分比转动，绿（≥40%）/ 黄（20–40%）/ 红（<20%）
• 桌面常驻：贴在桌面、不抢焦点；切到全屏 app 不跟过去、不遮挡前台
• 自由拖动 / 缩放：拖卡片移动，拖边或角缩放，内容等比适配、位置大小记住
• 右键设置：刷新间隔（1/2/4 小时）、代理、开机自启、窗口置顶、立即刷新
• 数据准、抓不到不空白：Codex 实时读取(合并 Cloud+CLI，与 codex /status 一致)，被 Cloudflare 拦时回退本地快照；Claude 被拦时显示「上次成功」值

系统要求

• macOS 13+
• Xcode 命令行工具（提供 swiftc）：xcode-select --install
• python3（命令行工具自带）
• 想看 Claude 额度：在 Chrome / Firefox 登录 claude.ai
• 想看 Codex 额度：用过 Codex CLI（本地 ~/.codex/sessions 才有额度快照）

安装

git clone https://github.com/cn-panda/claude-codex-quota.git
cd claude-codex-quota
bash install.sh

install.sh 会：本机编译（自动匹配 Intel / Apple Silicon）→ 在 ~/Library/Application Support/QuotaCard/venv 建 Python 环境装依赖 → 安装到 /Applications 并启动。

在「主桌面」运行安装/打开，卡片会绑定到桌面 Space。

使用

操作	效果
拖卡片中间	移动
拖边 / 角	缩放（内容等比适配）
右键	菜单：立即刷新 / 刷新间隔 / 代理 / 开机自启 / 窗口置顶 / 重置大小位置 / 退出

默认 直连；若访问 claude.ai 需要代理，右键 → 代理 → 自定义（如 127.0.0.1:7890）。

常见问题

打开提示「已损坏」或「无法打开，来自身份不明的开发者」？ 本工具未做苹果签名 / 公证。用 install.sh 安装会自动处理；若是手动拷贝的 .app，执行一次：

xattr -dr com.apple.quarantine /Applications/QuotaCard.app

或右键 app → 打开 → 仍要打开。

Claude 一直显示「上次成功」或 Cloudflare 错误？ claude.ai 会间歇性挑战非浏览器请求。多点几次右键「立即刷新」通常就过了，并确保 Chrome / Firefox 已登录 claude.ai。严格期会自行缓解。

Claude 显示「未读到 cookie / 登录失效」？ 在 Chrome 或 Firefox 登录 claude.ai。首次抓取会弹系统钥匙串授权（读取浏览器 cookie），点「始终允许」。

Codex 显示「本地 · N 小时前」、和 codex /status 对不上？ 正常时 Codex 走 chatgpt.com 实时接口，和 /status 一致。若显示「本地 · N 小时前」，说明实时接口这会儿被 Cloudflare 拦了、临时回退了本地快照——本地数据只在你用 Codex CLI 时写入，可能滞后,且不含 Cloud 网页用量。多点几次「立即刷新」通常就恢复实时了。

切到全屏 app 后卡片不见了？ 设计如此：卡片只在桌面 Space 显示，不跟进全屏 app、不遮挡前台。回到主桌面即可见。

卡片贴在了某个 app 上 / 绑错了桌面？ 在「主桌面」打开它（不要在全屏 app 的 Space 里打开）。退出后回到桌面重新打开即可。

拖不动？ 拖卡片中间 = 移动，拖边或角 = 缩放。想让它始终在最前方便操作，右键 →「窗口置顶」。

更新到新版本？

cd claude-codex-quota && git pull && bash install.sh

卸载？ 退出卡片后删除：/Applications/QuotaCard.app、~/Library/Application Support/QuotaCard，以及（若开过开机自启）~/Library/LaunchAgents/net.cnpanda.quota-card.plist。

工作原理

抓取脚本 fetch.py（随 app 打包到 Contents/Resources/，由独立 venv 运行）：

• Claude ← 读浏览器 cookie，请求 claude.ai usage API（用 curl_cffi 模拟 Chrome 指纹过 Cloudflare，带重试）。抓不到时回退「上次成功」缓存。
• Codex ← 优先请求 chatgpt.com 的 usage 接口(只读，不会触发新的 5h 窗口；合并 Cloud + CLI 用量，与 codex /status 一致)。被 Cloudflare 拦时回退本地 ~/.codex/sessions 最新快照——按 limit_id 取主账号桶 codex(实验模型如 Spark 各有独立配额，不会污染读数)，窗口过了重置点自动推断恢复满额。

已知局限（诚实说明）

• Cloudflare 间歇性拦截：claude.ai / chatgpt.com 偶尔挑战非浏览器请求。工具用 curl_cffi 模拟 Chrome 的 TLS 指纹(默认 chrome124，实测最稳)穿透，绝大多数时候能过；偶发被拦时 Claude 显示上次成功值、Codex 回退本地快照(橙色/灰色标注)。可用环境变量 AI_LIMIT_IMPERSONATE 换指纹版本。
• 回退到本地快照时：Codex 本地数据只反映 Codex CLI 的消耗、不含 Cloud 网页用量，且久未用 CLI 会旧——这是本地数据源的固有限制(官方 Codex CLI 本身也是同样来源)。实时接口正常时无此问题。
• 不读浏览器即无数据：未在 Chrome/Firefox 登录 claude.ai / chatgpt.com 时，对应服务显示错误。

隐私

只在本机读取：浏览器 cookie（经系统 Keychain 解密，首次会请求授权）、~/.codex/sessions 本地日志。不向任何第三方服务器上传数据。抓取直接发往 claude.ai / chatgpt.com 官方接口（与浏览器同源）。

从源码构建（开发）

bash build.sh        # 仅编译到 ./QuotaCard.app（含建 venv、生成图标）
open QuotaCard.app

项目结构：Sources/main.swift（全部 UI）、fetch.py（抓取）、icon.swift（图标生成）、Info.plist、build.sh / install.sh。

许可证

MIT