claude-quota: macOS 菜单栏 Claude Code 配额仪表盘

概述

claude-quota 是一款专为 macOS 设计的菜单栏实用程序，旨在提供 Claude Code 配额使用情况的即时可视化。该工具作为 SwiftBar 插件构建，允许用户直接从 macOS 菜单栏监控其 5 小时窗口利用率和每周限制，从而无需再手动在 Claude Code CLI 中运行 /usage 命令。

核心功能与视觉指示器

该工具使用颜色编码的仪表盘系统，以便一眼就能识别配额状态：

  • 5 小时窗口利用率： 仪表盘颜色为绿色、橙色（当 $\ge 70%$ 时）或红色（当 $\ge 90%$ 时）。
  • 重置倒计时： 当 5 小时窗口完全耗尽时，仪表盘会将百分比替换为直到下次重置的倒计时器（例如 4:28）。
  • 每周限制警报： 如果达到每周限制，仪表盘将变为黑色并显示每周重置的倒计时（例如 2D）。此每周上限的优先级高于 5 小时窗口状态。
  • 详细下拉菜单： 点击仪表盘会显示每个账户的详细明细，包括 5 小时和每周窗口、各模型窗口（如果适用）、额外使用额度以及准确的重置时间。
  • 刷新率： 插件默认每 5 分钟刷新一次，下拉菜单中提供手动“Refresh now”选项。

技术实现

数据检索

claude-quota 通过以只读方式从 macOS Keychain 中读取 Claude Code OAuth 令牌，从而检索使用数据。然后，它会查询与 Claude Code /usage 界面使用的相同的内部、未公开的端点。由于它不会刷新或重写令牌，因此它不会导致用户退出登录。

账户管理

默认情况下，插件通过扫描具有关联 Keychain 条目的 ~/.claude 或 ~/.claude-* 配置目录来自动发现账户。

  • 标签化： 自动发现的账户通过目录后缀进行标记（例如，~/.claude-work 变为 W）。单个账户则不显示标签。
  • 自定义： 用户可以通过在 ~/.config/claude-quota/accounts 创建一个配置文件，每行一个 path [label] 来固定或重命名账户。
  • 可见性： 可以通过下拉菜单或编辑 ~/.config/claude-quota/hidden 将特定账户从菜单栏仪表盘中隐藏。

安装与设置

快速安装

用户可以通过 shell 脚本安装该工具： curl -fsSL https://raw.githubusercontent.com/grzegorz-raczek-unit8/claude-quota/main/install.sh | bash

手动安装

或者，用户可以从 git checkout 进行安装：

  1. git clone https://github.com/grzegorz-raczek-unit8/claude-quota.git
  2. cd claude-quota
  3. ./install.sh

要求： 该工具需要 macOS 和 Homebrew。在首次刷新时，当 macOS Keychain 权限对话框出现时，用户必须选择“Always Allow”。

社区讨论与替代方案

Hacker News 上的社区反馈强调了多种用于跟踪 AI 配额使用情况的替代工具，表明了类似实用程序的生态系统非常拥挤。用户提到了以下几种替代方案，包括：

  • CodexBar 和 usage4claude：支持包括 Codex 在内的多个提供商的工具。
  • ClaudeCodeStatusLine：一个将使用数据直接集成到 Claude Code CLI 状态栏的插件。
  • codeburn 和 RateLimited：其他菜单栏或基于终端的跟踪器。
  • claudebar：基于 Linux 的 Hyprland/Waybar 替代方案。

一些用户对安装方法（将 curl 管道传输到 bash）表示了担忧，而其他用户则指出，Claude Code CLI 状态栏中缺乏原生配额指示器是促使这些第三方工具诞生的主要驱动力。

Sources