codenotch

这是什么？适合谁？

Codenotch 是一个 macOS 原生开源应用：它在屏幕边缘钉一枚小黑缺口（notch），实时显示你已把各 AI 编码助手的用量上限烧掉了多少——以及它现在是在干活、干完了，还是在等你。悬停即可查看每个 provider 的限额窗口与重置时间。

它解决的是多 AI 编码工具使用者的真实痛点：Claude Code、Cursor、Codex、Antigravity、GLM 各有各的限额规则与重置窗口，没有厂商提供干净的「你的会话限额已用 N%」API，用户只能在被 429 拦截时才知道额度耗尽。Codenotch 把这些分散的信号集中到一眼可见的位置。

核心价值：多 AI 编码助手限额的常驻可视化——读数全部借自你 Mac 上已登录工具自有的凭证或会话（官方端点 / 本地 SQLite / 语言服务器 RPC），Codenotch 自己不在任何地方登录；每个 adapter 声明自己的保真度（official / derived / manual），失败降级为可见状态（stale / needsAuth / error）而不是编造百分比。

适合人群：

• 同时使用 Claude Code + Cursor / Codex / Antigravity / GLM 编码计划、经常被限额打断的开发者
• 工作账号与个人账号分开（CLAUDE_CONFIG_DIR=~/.claude-work claude）、需要同时盯两套限额的用户
• 想在 429 发生前提前规划任务切换的深度 AI 编码用户

使用前提：macOS（Swift 原生应用）；本机已安装并登录至少一个被支持的编码工具——你装了谁，谁的环就出现。

准备工作

1. 系统：macOS（Apple Silicon / Intel 均可），无需独立账号——Codenotch 不注册、不登录任何服务
2. 环境：Xcode Command Line Tools（xcode-select --install）；brew install xcodegen（构建期一次性）
3. 成本：MIT 开源免费，纯本地读取，无任何订阅
4. 时间：克隆 + make run 约 2-3 分钟出 Debug 构建
5. 官方发布：仓库尚处早期（2026-09-05 创建），暂无打包发行版，需自行构建（见踩坑 1）

快速上手（3 步）

第一步：克隆并构建

git clone https://github.com/vinzdg/codenotch.git && cd codenotch
brew install xcodegen   # 一次性
make run                # 生成工程、构建并启动 Debug 版

make run 会用 xcodegen 生成 Xcode 工程、编译并直接启动。不需要签名身份。

第二步：授权并观察缺口

首次启动后，屏幕边缘出现一枚小药丸（pill），指针靠近时展开为读数。此时给它读取凭证的授权：

• 首次读取 Claude Code / Antigravity 的钥匙串项时，macOS 弹出「Always Allow」提示——应用以稳定 Developer ID 身份签名，授权在重建后仍然有效
• 你已登录的每个工具的环自动出现：Claude Code、Cursor、Codex、Antigravity、GLM（Z.ai Coding Plan）

第三步：跑一次完整验证

make test               # 单元测试
CODENOTCH_DEMO=1 make run   # 以固定样例数据模式启动，无真实凭证也能看到完整 UI

预期结果：缺口处显示各 provider 的用量环；环内有细弧旋转表示会话忙碌中；阻塞等待你时变为琥珀色脉冲环；悬停显示限额窗口、重置时间与全部活跃会话。

初级用法

查看限额窗口与重置时间

悬停任意 provider 的环，即可看到它当前的限额窗口与重置时间。Claude 的环与 Claude Code 自带 /usage 命令首屏显示的当前会话窗口一致，两边永不打架。

感知「它还在干活吗」

• 环内细弧旋转 = 会话忙碌中
• 琥珀色脉冲环 = 被阻塞、正在等你（悬停可见是哪个会话、跑在哪、想要什么）

多工作区分环

两个 Claude Code 登录就是两个环。用 CLAUDE_CONFIG_DIR=~/.claude-work claude 把工作账号分开的用户，会得到一个 Claude (work) 环与个人环并排显示——各自限额、各自会话、设置里各自一行。任何 ~/.claude-<slug> 目录都会在启动时被发现，默认 ~/.claude 永远排第一，其余按字母序——环不会换位置。

高级玩法

位置与形态定制

缺口可钉在四条屏幕边任意一条：左右为纵列布局，上下为横排。它会自动贴合可用边缘——底部放置时落在 Dock 上并跟随 Dock 隐藏/移动；有硬件缺口的 Mac 上，顶部放置会精确贴合硬件缺口形状。设置里可改为常显或完全隐藏。

隐私精细控制

在设置（缺口下方的小球：静止时是弧，悬停时是齿轮）里关闭某个 provider，即停止读取该 provider 的凭证并遗忘已取读数——但不会把你登出拥有该账号的工具，界面上也会如实说明。

自动更新

内置 Sparkle 每日检查更新并后台静默安装，可在设置中关闭。每个更新都经 EdDSA 签名——未由维护者构建签名的任何东西都不会被安装。

小技巧

1. CODENOTCH_DEMO=1 启动可看到固定样例数据，适合截图、演示或无凭证环境验证 UI
2. Cursor 的读数直接借编辑器自己的登录会话（本地 SQLite 状态），无需在 Codenotch 里再登录一次
3. GLM 环的 key 借自你机器上已持有它的任一工具（Claude Code 的 settings.json、ZCode 或 OpenCode）
4. Claude 端点被轮询太狠会返回 429：应用内部有 60 秒起步、逐次翻倍、上限 15 分钟的退避，且惩罚截止时间持久化——重启也不会立刻重撞
5. 应用可显示 Dock 图标、菜单栏图标或两者都不显示，全屏工作时选「都不显示」最干净

常见踩坑

踩坑 1：找不到安装包 / Release

• 现象：仓库 Releases 页为空，只有源码
• 原因：项目 2026-09-05 刚创建，官方签名发行版尚未切出（make release 需要维护者的 Developer ID 证书走公证流程）
• 解决：按快速上手自行 make run 构建；后续关注仓库 Release 页
  • 来源：CONTRIBUTING/README

踩坑 2：首次读取凭证反复弹授权框

• 现象：每次轮询都弹钥匙串授权
• 原因：自建 Debug 构建签名身份不稳定，「Always Allow」授权未跨构建存活
• 解决：应用以稳定 Developer ID 身份签名；且密钥仅在所属 app 真正改过它时才重读（用钥匙串项的修改日期判断，该日期不受凭证同款访问提示约束），有效授权≠每次轮询都弹窗
  • 来源：官方 README「Keychain」节

踩坑 3：某个环显示 stale / needsAuth / error

• 现象：读数不更新或显示状态字样
• 原因：各 adapter 读取的是所属工具自己的数据源（内部端点、本地数据库、语言服务器 RPC），上游改版会随时失效——这是所有此类工具的共同命运，README「The honest caveat」一节明说
• 解决：更新对应工具或等待 Codenotch 更新；应用从不把猜测伪装成厂商公布的数字，每个 adapter 的响应结构都有测试钉死
  • 来源：官方 README

踩坑 4：换了终端/工具后环消失

• 现象：某 provider 的环不见了
• 原因：凭证读取借自你机器上已登录的工具——你没装/没登录的工具不会出现环
• 解决：安装并登录对应工具，其环自动出现；或在设置中确认该 provider 未被关闭

踩坑 5：Antigravity 环显示的是请求数而非百分比

• 现象：与其他环的展示形式不同
• 原因：Antigravity 的保真度分级为「有许可处官方、否则请求计数」——本地语言服务器优先，其次 Google 配额端点，两者都不应答时退化为纯计数
• 解决：这是如实标注的设计（Fidelity 分级），不是故障

常见问题 FAQ

Q1: Codenotch 需要我提供任何账号或 API key 吗？

A: 不需要。它从不在任何地方登录，所有读数借自你 Mac 上已登录工具自有的凭证或会话。装好并登录任一被支持的工具，其环自动出现。

Q2: 免费吗？开源吗？

A: MIT 开源免费，纯本地运行，无订阅、无遥测后端、无 API 计费。

Q3: 和系统活动监视器 / 各工具自带 /usage 的区别？

A: 各工具自带的用量视图彼此割裂（Claude 的 /usage 只看 Claude）；Codenotch 把五家 provider 的限额聚合到同一枚缺口，且 Claude 读数与 /usage 首屏的当前会话窗口严格一致。它还回答「它还在干活吗」——忙碌/等待状态与活跃会话列表是活动监视器给不了的。

Q4: 支持哪些 AI 编码工具？

A: Claude Code（官方端点）、Cursor（编辑器自有会话）、Codex（其 app server 实时限额，Codex 未运行时回退 rollout 日志）、Antigravity（有许可处官方，否则请求计数）、GLM / Z.ai Coding Plan。每个 adapter 声明自己的保真度，UI 不把猜测当官方数字呈现。

Q5: 会在 429 之前提醒我吗？

A: 缺口实时显示已烧掉的额度比例与重置窗口，让你在撞 429 之前主动规划；Claude 端点自身的 429 退避（60s 起步、翻倍、上限 15 分钟、持久化截止时间）在应用内部处理，不会因频繁轮询把你的账号打入惩罚期。

进阶学习建议

1. 读 Sources/Providers/ 里每个 provider 的 UsageProvider 实现与 Fidelity 声明（.official / .derived / .manual），理解「读数保真度分级」如何防止 UI 把猜测当官方数字
2. 读 Sources/Model/ 的 UsageStore：定时轮询、跨启动保留最后一次有效读数、一切失败降级为可见状态——这套降级策略值得任何状态聚合类工具借鉴
3. 研究 NotchPlacement 与一维 stack space（along/across）设计：缺口 UI 与四条屏幕边解耦，布局尺寸全部引用设计稿 docs/design/frame-124-hover-tooltip.png，可对照核验
4. 对照 docs/specs/2026-08-28-usage-notch-design.md 设计规格与 TASKS.md 实现史，看一个从设计稿到测试钉死的 macOS 小工具完整流程

参考链接

• 官方仓库
• README（读数来源、构建、架构与诚实声明）
• 设计规格 docs/specs/2026-08-28-usage-notch-design.md
• CONTRIBUTING.md（构建与发布流程）

最后更新：2026-09-07 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成