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 token 來檢索使用數據。接著，它會查詢與 Claude Code /usage 畫面所使用的相同內部且未公開的端點。由於它不會重新整理或重寫 token，因此不會導致使用者登出目前的會話。

帳戶管理

預設情況下，插件會透過掃描具有相關 Keychain 條目的 ~/.claude 或 ~/.claude-* 配置目錄來自動發現帳戶。

  • 標籤化： 自動發現的帳戶會根據目錄後綴進行標籤化（例如：~/.claude-work 會變成 W）。單一帳戶則不顯示標籤。
  • 客製化： 使用者可以透過在 ~/.config/claude-quota/accounts 建立一個配置文件，每行寫入一個 path [label] 來釘選或重新命名帳戶。
  • 可視性： 特定帳戶可以透過下拉選單從選單列儀表隱藏，或透過編輯 ~/.config/claude-quota/hidden 來隱藏。

安裝與設定

快速安裝

使用者可以透過 shell script 安裝此工具： 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：適用於 Hyprland/Waybar 的 Linux 版本替代方案。

部分使用者對安裝方式（將 curl 管道傳遞給 bash）表示擔憂，而其他人則則指出，Claude Code CLI 狀態列缺乏原生配額指示器，是開發這些第三方工具的主要驅動力。

Sources