Codenotch：把 Claude Code / Cursor / Codex 的额度「挂」在屏幕边缘，一眼看清还要多久被限流

写代码写到一半，Claude Code 突然告诉你「当前会话额度已用尽」——这种猝不及防，几乎每个重度使用 AI 编程助手的人都经历过。问题不在于额度本身，而在于你根本不知道还剩多少。你不知道当前 5 小时窗口烧到了 73% 还是 12%，也不知道它什么时候重置。

Codenotch 就是为解决这个「盲区」而生的开源 macOS 小工具：它把一个黑色小胶囊（notch）钉在屏幕边缘，用一圈圈环形进度条实时显示各路 AI 编程助手烧掉了多少额度。项目由 vinzdg 开源，MIT 协议，2026 年 9 月刚发布就冲上 GitHub Trending，目前约 1386 stars。

!Codenotch 边缘额度监控

它到底解决什么问题

现在的 AI 编程工具几乎都采用订阅制 + 额度窗口：Claude Code 有「当前会话」和「所有模型」两个窗口，Codex 有 5 小时和每周限制，Cursor 有它自己的一套计数。这些数字散落在各个工具的 /usage 命令、设置面板或网页后台里，没人愿意每隔十分钟去翻一次。

Codenotch 的做法很直接：把这些数据全部聚合到一个常驻屏幕边缘的小挂件里。环形进度条外圈的颜色会随用量变化，鼠标悬停就能看到具体窗口和重置时间——Claude 的环形显示的是 Claude Code 自己 /usage 里那个「当前会话」窗口，所以两边永远不会打架。

支持哪些工具

这是 Codenotch 最实在的地方，它支持的 provider 列表相当长，而且明确标注了数据来源的可信度分级（.official / .derived / .manual）：

• Claude Code：优先读 Claude Desktop 自己缓存的 usage 响应（只读、按组织 ID 精确匹配），其次问已安装的 claude 的 /usage，最后才用登录钥匙串里的 OAuth token

• Cursor：直接读编辑器本地 SQLite 里的登录会话，或 cursor-agent 的钥匙串登录，无需二次登录

• Codex：用本地 Codex 登录信息请求 ChatGPT 的 usage 端点，展示 5 小时与每周限制

• Antigravity：优先本地语言服务器，其次 Google 配额端点

• GLM：借 Z.ai Coding Plan 的监控端点，密钥从 Claude Code 的 settings.json、ZCode 或 OpenCode 里借用

• Ollama（本地）：自动探测本地模型、RAM/VRAM、卸载时间和上下文，可选开启生成速度（tok/s）与思考过程捕获

• Grok：读 ~/.grok/auth.json 里的 Grok CLI 会话

• OpenCode：用 OpenCode 自己存的 opencode-go 密钥请求官方 usage 端点

• Command Code：读应用写入 ~/.commandcode/auth.json 的密钥

• GitHub Copilot：用 Mac 上已有的 GitHub CLI 会话（gh auth login）认证配额端点

大多数 provider 都是借用你机器上已登录工具的凭据或会话，不需要在 Codenotch 里重新登录一遍。

它还能回答「它还在干活吗？」

除了额度，Codenotch 还想解决第二个焦虑：AI 是还在跑，还是卡住等你确认了？

• 某个 provider 正在忙时，它的环形里会有一道细弧线旋转

• 当会话阻塞、等待你输入时，环会变成脉冲的琥珀色

• 悬停可以看到每一个活动会话的名字、运行位置和它想要什么

• 会话结束时，notch 会自动展开 5 秒并播放系统提示音，点击即可把对应应用拉到前台

这个「拉前台」的细节写得很克制：会话只发布自己的 pid，应用通过沿着进程树向上走找到，而不是去猜终端标签页——因为 Terminal.app 和 iTerm2 能按 tty 匹配标签，但 Warp 和 Ghostty 根本没有脚本接口。所以它选择只抬升应用、在 tooltip 里点名会话，把最后一步留给你一个按键，而不是在两个终端上工作、在第三个上静默失效。

双账号、多窗口隔离

用工作账号和个人账号的人会很受用：

• 通过 CLAUDE_CONFIG_DIR=~/.claude-work claude 开的第二个 Claude 账号，会拥有一个并列的 Claude (work) 环，有自己的额度、会话和设置行

• 任何 ~/.claude- 目录，只要 Claude Code 跑过，启动时都会被自动发现

• Codex 同理：~/.codex 是默认环，每个用过的 ~/.codex- 会添一个 Codex (slug) 环

默认目录永远排第一，其余按字母序排列，所以环的位置不会来回跳。

告警与放置

• 某个 provider 的头部额度跨过 80% 和到达 100% 时各触发一次系统通知，跨过期间不重复提醒，窗口真正重置后才重新计数

• 每个 provider 可单独静音，macOS 权限在第一次真实告警时才申请，而不是启动时就弹

• notch 可以钉在四条屏幕边的任意一条：左右是竖排，上下是横排；按住 Option 拖动可沿边移动，每条边各自记住位置

• 在有硬件刘海的 Mac 上，顶部放置会精确贴合刘海形状，两者看起来融为一体

• 外观里的大小设置能统一缩放整个 notch（环形、文字、tooltip 一起变）

关于数据的诚实说明

README 里有一段标题就叫 「The honest caveat」（诚实的警告），这在开源项目里相当难得：

没有任何厂商为这些工具提供干净的「你的会话额度已用 N%」API。

所以每个 adapter 都是读取拥有该数据的应用自己所读的东西——内部端点、本地数据库、语言服务器的 RPC——这些接口随时可能变化。项目用测试固定了每个 adapter 的响应结构，并且所有失败都会降级为可见状态（stale / needsAuth / error），而不是编一个百分比出来。

几个工程细节也值得一提：

• Claude Desktop 缓存：Claude Desktop 是 Chromium 应用，它自己面板画的 usage 响应会写进 ~/Library/Application Support/Claude 下的 HTTP 缓存。Codenotch 严格只读，且只打开缓存 URL 属于当前账号 /api/organizations//usage 的条目，按 Claude Code 记录的组织 ID 匹配，确保一个账号的数字绝不会落到另一个账号的环上

• zstd 解码：缓存体是 content-encoding: zstd，而 macOS 不带解码器，于是项目 vendored 了一个只做解码的 Zstandard 构建（BSD-3-Clause）

• Keychain 陷阱：Claude Code 每次 token 轮换都会新建钥匙串条目，新条目不再包含本应用的访问许可，所以一小时前授予的「始终允许」会失效。Codenotch 的做法是干脆去问 claude 本身，绕开这个坑

• 限流退避：Claude 端点被轮询太狠会返回 429，且带一个没用的 Retry-After: 0。项目的退避把它当作下限抬高器——60 秒起步、每次连续 429 翻倍、封顶 15 分钟——并持久化截止时间，所以惩罚期内重启也是等待而不是浪费一次尝试

• 空闲降频：没有任何会话在跑时，轮询降到 5 分钟一次，右键 notch 可以「立即刷新」

安装

官方提供签名、公证、可自更新的 DMG，直接下载 Codenotch.dmg 即可。要求 macOS 15 或更高，Universal 二进制。

从源码构建：

brew install xcodegen   # 只需一次
make run                # 生成、构建、启动 Debug 版
make test               # 单元测试

make release（归档、公证、产出带签名的自动更新 feed）需要 Developer ID 证书，只有维护者会跑。想在没有 Xcode 的情况下试未发布的 main 分支，可以用项目仓库的预览构建，但它是 ad-hoc 签名的，会被 macOS 隔离，拖到 Applications 后跑一次即可解除：

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

架构一览

每个 provider 实现 UsageProvider（Sources/Providers/）并声明自己的 Fidelity（.official / .derived / .manual），这样 UI 就不会把猜测当成厂商发布的数据来展示。UsageStore（Sources/Model/）按定时器轮询它们，跨启动保留最后一次有效读数，并把每次失败降级为可见状态。

notch 本身工作在一维的 stack space（along / across）里，与它在哪条屏幕边无关；NotchPlacement 是唯一把这些映射回真实屏幕坐标的地方。NotchLayout 保存所有尺寸，且直接引自设计稿 docs/design/frame-124-hover-tooltip.png，方便逐帧比对。

更新走 Sparkle，每天检查、后台静默安装；每次更新都有 EdDSA 签名，所以不会装进来不是由维护者构建并签名的东西。