使用 Codenotch 监控 macOS 上的编程助手额度

Codenotch 是什么？

Codenotch 是一款 macOS 应用，可将紧凑的黑色凹口固定在屏幕的任意边缘。其环形指示器会显示每个受支持的编码助手已消耗的使用限额，以及会话当前处于活动、已完成还是等待输入状态。

闲置时，凹口会保持为一个小胶囊形；当指针移至其上时会展开。将鼠标悬停在提供商环形指示器上，可查看其限额时间窗口和重置时间。对于 Claude Code，主环形指示器代表 Claude Code 的 /usage 命令首先显示的同一个当前会话窗口。

Codenotch 还会监控会话活动。会话繁忙时，提供商环形指示器内会有一段细弧旋转。如果会话需要你的关注，环形指示器会变为脉动的琥珀色状态。悬停后可查看实时会话名称、运行位置以及所需操作。

支持的提供商和数据来源

Codenotch 不维护独立的账户系统，也不会要求你登录。它会读取 Mac 上受支持工具已经保存的凭据或会话。

• Claude Code：使用登录钥匙串中存储的 OAuth 令牌，并查询 Claude Code 的 /usage 命令所使用的同一端点。
• Cursor：从其本地 SQLite 状态中读取编辑器已登录的会话。
• Codex：向正在运行的 Codex 应用服务器请求当前速率限制。如果 Codex 未运行，Codenotch 会回退到其运行记录日志。
• Antigravity：先尝试本地语言服务器，然后尝试 Google 的配额端点。当两者都无法提供该账户的配额数据时，它会显示普通请求计数。
• GLM：使用 Claude Code 的 settings.json、ZCode 或 OpenCode 中已保存的密钥，调用 Z.ai 的 Coding Plan 监控端点。

按正常方式安装并登录受支持的工具。当 Codenotch 发现其本地会话或凭据后，相应的环形指示器就会出现。在设置中停用某个提供商，会停止 Codenotch 读取该凭据，并删除已保存的读数，但不会让你退出原始工具。

主要功能

• 支持 Claude Code、Cursor、Codex、Antigravity 和 GLM 的使用量环形指示器。
• 将鼠标悬停在环形指示器上即可查看重置时间窗口详情。
• 实时显示编码会话的繁忙和等待状态。
• 自动发现多个 Claude Code 配置。
• 可放置在屏幕顶部、底部、左侧或右侧边缘。
• 根据可用屏幕区域、程序坞位置和硬件凹口自适应布局。
• 可选择显示程序坞图标、菜单栏图标，或两者都不显示。
• 通过 Sparkle 每日后台检查更新。
• 显示可见的 stale、needsAuth 和 error 状态，而不是估算百分比。

构建并运行 Codenotch

前置条件

该项目是使用 XcodeGen 生成的 macOS 应用。使用 Homebrew 安装一次 XcodeGen：

brew install xcodegen

在仓库的本地检出目录中生成项目、构建项目并启动 Debug 构建：

make run

Debug 构建不需要签名身份。

运行测试

使用项目的测试目标来验证提供商适配器及其他行为：

make test

测试会固定提供商响应的结构，因为底层内部端点、本地数据库和 RPC 接口可能在没有通知的情况下发生变化。

使用演示数据

如果你想在不读取实时提供商数据的情况下检查界面，请使用 CODENOTCH_DEMO=1 启动应用：

CODENOTCH_DEMO=1 make run

演示模式提供固定的示例数据，适用于界面开发、布局检查和截图。

make release 不属于常规本地设置流程。它需要 Developer ID 证书和 App Store Connect 公证配置文件，由维护者用于归档、公证并生成已签名的自动更新源。

基本使用

1. 通过提供商自己的工具登录

打开你想要监控的编码工具，并在其中登录。Codenotch 从不自行执行登录。例如，像平常一样通过 Claude Code 或 Cursor 完成身份验证，然后启动 Codenotch。

2. 查看提供商环形指示器

每个被发现的提供商都会以环形指示器的形式显示在凹口中。通过环形指示器了解可用限额已经消耗了多少。将鼠标悬停在其上，可查看可用的限额时间窗口及其重置时间。

3. 查看会话状态

受支持的会话运行时，请留意其环形指示器内旋转的细弧。脉动的琥珀色环表示会话已被阻塞，正在等待你的操作。悬停后可查看会话名称、位置和请求的操作。

4. 配置凹口

通过凹口下方的圆形按钮打开设置。静止时它显示为弧线，悬停后会变为齿轮。设置可以控制凹口是否在悬停时展开、保持可见，或完全隐藏。

你还可以选择 Codenotch 是否显示程序坞图标、菜单栏图标，或两者都不显示。

5. 选择屏幕边缘

将凹口放置在四个边缘中的任意一个：

• 左侧或右侧：提供商读数以垂直列显示。
• 顶部或底部：提供商读数并排显示。

Codenotch 会沿屏幕的可用边缘排列。放置在底部时，它会位于程序坞上方，并在程序坞隐藏或移动时作出响应。在配备硬件凹口的 Mac 上，顶部放置会采用硬件凹口的精确形状，使实体凹口和软件凹口看起来像一个整体。

监控多个 Claude Code 账户

Codenotch 可以为不同的 Claude Code 配置目录显示独立的环。例如，可以使用以下命令启动工作账户：

CLAUDE_CONFIG_DIR=~/.claude-work claude

Claude Code 使用该目录后，Codenotch 会发现它，并在个人账户旁显示一个 Claude (work) 环。工作账户拥有独立的限额、会话和设置行。

启动时，Codenotch 会查找 Claude Code 使用过的、符合 ~/.claude-<slug> 格式的目录。默认的 ~/.claude 账户始终排在第一位，其他配置按字母顺序排列，因此各个环的位置不会意外改变。

刷新行为和速率限制

Codenotch 会调整轮询频率，以减少不必要的请求。当没有正在运行的受监控会话时，轮询会降低到每五分钟一次。若要手动请求最新数据，请右键点击缺口并选择 立即刷新。

Claude 的端点在查询过于频繁时可能返回 HTTP 429。Codenotch 会应用逐步增加的延迟：从 60 秒开始，在连续收到速率限制响应后翻倍，最长为 15 分钟。该截止时间会在多次启动之间保持不变，从而避免应用重启后立即再次消耗一次尝试机会。

更新和安全性

Codenotch 使用 Sparkle 每日检查更新，并在后台安装更新。可以在设置中禁用自动更新。官方更新使用 EdDSA 签名，因此应用不会安装未经维护者生成和签名的构建版本。

对于基于钥匙串的提供程序，官方应用使用稳定的 Developer ID 身份，因此一次性的 始终允许 授权可以在重新构建后继续有效。Codenotch 会在再次读取密钥前检查钥匙串项目的修改日期，从而减少例行轮询期间反复出现的访问提示。

高级开发说明

提供程序架构

每个集成都在 Sources/Providers/ 下实现 UsageProvider。提供程序还会声明一个 Fidelity 值：.official、.derived 或 .manual。这样可以避免界面将推断出的值呈现为供应商直接公布的值。

位于 Sources/Model/ 下的 UsageStore 会按计时器轮询提供程序，并在多次启动之间保留上一次成功读取的数据。当提供程序失败时，存储会显示 stale、needsAuth 或 error 等可见状态，而不是虚构一个百分比。

屏幕边缘布局

缺口布局使用 along 和 across 坐标，在一维堆叠空间中运行。NotchPlacement 会将这些值映射为所选边缘上的实际屏幕坐标。NotchLayout 集中管理用于将实现与设计稿进行对比的尺寸。

查看诊断日志

由于 Codenotch 没有传统的应用窗口，诊断信息会写入 macOS 统一日志。使用以下命令流式传输调试消息：

/usr/bin/log stream --predicate 'subsystem == "com.vinz.codenotch"' --level debug

当提供程序无法进行身份验证、返回过时数据或遇到响应格式变化时，这是主要的故障排查工具。

了解局限性

目前没有受支持的供应商发布一种简单、稳定且能够普遍将编码会话报告为精确已用百分比的 API。因此，Codenotch 会读取所属应用使用的相同内部或本地来源，包括端点、数据库、语言服务器和日志。

这些接口可能在没有通知的情况下发生变化。Codenotch 通过适配器测试和明确的失败状态来应对这一风险，但上游应用发生变化后，提供程序集成仍可能暂时停止工作。

结语

Codenotch 将编码助手使用量、重置窗口和活动会话状态整合到 macOS 屏幕边缘的一小块显示区域中。使用 make run 开始，通过演示模式安全地探索界面，然后让应用发现受支持工具中已经配置的账户。有关开发和贡献的详细信息，请参阅 CONTRIBUTING.md。本项目采用 MIT License 授权。