Show HN: macOS 菜单栏的 Claude Code 配额仪表盘

背景

随着 AI 编程助手 Claude Code 的普及，许多开发者开始使用多个 Anthropic 账户或不同的配置目录（CLAUDE_CONFIG_DIR）来管理不同的项目或身份。然而，Anthropic 对 API 调用设有严格的配额限制，包括每 5 小时的短期窗口限制和每周的硬性上限。

目前，Claude Code 的 /usage 界面虽然提供了用量查询功能，但缺乏直观的实时监控手段，尤其是在 macOS 系统层面。开发者往往需要手动打开终端或浏览器才能确认剩余配额，这在快速迭代的开发流程中显得不够便捷。此外，由于该用量接口属于内部未文档化接口，第三方工具的开发存在一定风险。在此背景下，开发者 grzegorz-raczek-unit8 发布了一款名为 claude-quota 的 macOS 菜单栏小部件，旨在为 Claude Code 用户提供直观、实时的配额监控体验。

核心内容

该工具是一个基于 SwiftBar 的 macOS 菜单栏插件，专门用于可视化展示 Claude Code 的 API 配额使用情况。其核心功能和运行机制如下：

1. 可视化配额监控

• 单账户单条目：每个 Claude Code 账户在菜单栏中显示为一个独立的进度条。
• 颜色编码状态：
  • 绿色：正常用量。
  • 橙色：5 小时窗口内用量达到或超过 70%。
  • 红色：5 小时窗口内用量达到或超过 90%。
• 倒计时显示：
  • 当 5 小时窗口用尽时，进度条不再显示百分比，而是显示距离重置的倒计时（例如 4:28）。
  • 当触及每周硬性上限时，进度条变为黑色，并显示距离每周重置的倒计时（例如 2D，即 2 天）。这是最高优先级的限制状态。

2. 详细数据下拉菜单

点击菜单栏图标可展开下拉菜单，显示每个账户的详细信息，包括：

• 5 小时窗口和每周窗口的当前用量。
• 特定模型的窗口限制（如果订阅计划中提供）。
• 额外用量积分（Extra-usage credits）。
• 各窗口的重置时间。

3. 数据获取与安全机制

• OAuth Token 读取：插件通过只读方式从 macOS 钥匙串（Keychain）中读取 Claude Code 的 OAuth Token。
• 安全性承诺：插件不会刷新或重写 Token，因此无法导致用户登出；不收集密码；不进行网页抓取（Scraping）；不依赖任何第三方服务。
• 数据源：直接查询 Claude Code 的 /usage 屏幕所使用的相同内部 API 端点。
• 风险提示：由于该端点属于 Claude Code 内部接口且未公开文档化，Anthropic 未来的更新可能导致接口变更，从而需要对该插件进行小幅修复。

4. 自动化与配置

• 自动发现账户：默认情况下，插件会自动扫描 ~/.claude 和 ~/.claude-* 目录。只要这些配置目录在 macOS 钥匙串中有对应的 Claude Code 条目，就会自动生成一个菜单栏条目。
  • 标签命名规则：基于目录后缀（例如 ~/.claude-work 显示为 W）。
  • 如果只有一个自动发现的账户，则不显示字母标签，仅显示进度条。
• 手动配置：
  • 固定/重命名账户：通过创建 ~/.config/claude-quota/accounts 文件，按 [路径] [标签] 格式每行定义一个账户（标签需为单字）。
  • 隐藏账户：在下拉菜单中点击“Hide from menu bar”或编辑 ~/.config/claude-quota/hidden 文件，可隐藏特定账户的菜单栏进度条（但下拉详情仍可见）。
• 多账户 Shell 配置示例：

  claude() { CLAUDE_CONFIG_DIR="$HOME/.claude-work" command claude "$@"; }
  claude-priv() { CLAUDE_CONFIG_DIR="$HOME/.claude-priv" command claude "$@"; }
  

5. 安装与维护

• 依赖要求：macOS 系统，需安装 Homebrew 和 SwiftBar。
• 安装方式：
  • 一键脚本：curl -fsSL https://raw.githubusercontent.com/grzegorz-raczek-unit8/claude-quota/main/install.sh | bash
  • 源码安装：git clone 仓库后运行 ./install.sh。
• 权限设置：首次刷新时，macOS 会弹出钥匙串权限对话框，用户需选择“始终允许”（Always Allow）。
• 故障排除：如果账户显示 ⚠ 警告，通常是因为 Token 因长期未使用而过期。只需运行一次 claude CLI 命令，插件在下一个刷新周期即可自动恢复。
• 刷新频率：默认每 5 分钟刷新一次，也可在下拉菜单中手动点击“Refresh now”。
• 卸载：删除 SwiftBar 插件文件夹（默认为 ~/.swiftbar）中的 claude-quota.5m.py 文件即可。

关键要点

• 实时可视化：通过颜色（绿/橙/红/黑）和倒计时直观展示 5 小时窗口和每周硬限的配额状态，避免意外超额。
• 安全本地化：数据完全在本地 macOS 钥匙串中读取，不上传任何数据至第三方服务器，且仅读取 Token 不修改 Token。
• 多账户支持：自动识别 ~/.claude-* 配置目录，支持通过配置文件自定义标签和隐藏特定账户，适合拥有多个 Anthropic 账户的高级用户。
• 内部接口依赖：依赖 Claude Code 未文档化的内部 /usage 端点，存在因上游更新而失效的风险，需用户自行关注维护。
• 轻量级集成：基于 SwiftBar 生态，安装简单，无需复杂配置即可快速上手，刷新频率为 5 分钟。

意义与影响

这款工具的出现反映了 AI 开发工具链向“可观测性”和“精细化运营”发展的趋势。对于重度依赖 Claude Code 的开发者而言，API 配额不仅是成本控制的核心，也是保证开发连续性的关键资源。

1. 提升开发效率：将配额监控从“主动查询”转变为“被动感知”，开发者无需中断编码流程即可掌握资源状况，降低了因配额耗尽导致的中断风险。
2. 社区驱动的工具生态：该工具由社区开发者基于逆向工程（使用内部 API）构建，体现了开源社区对主流 AI 工具生态的补充作用。它填补了官方工具在 macOS 系统级集成上的空白。
3. 潜在的不稳定性：由于依赖未文档化的内部 API，该工具的生命周期取决于 Anthropic 的接口稳定性。这提醒用户，此类非官方工具可能存在随时失效的风险，建议仅作为辅助监控手段，而非关键业务依赖。
4. 隐私与安全的平衡：在利用内部接口的同时，该工具严格遵守本地化处理原则，不引入额外的数据泄露风险，为同类工具提供了良好的安全实践参考。