richhickson/claudecodeusage

macOS menu bar app showing Claude Code usage limits (session/weekly/per-model/overage) with alerts and click-to-focus when a Claude Code session needs your attention

Claude Usage – macOS 菜單列輔助工具，適用於 Anthropic Claude Code

這是什麼 – 一個輕量級的原生 Swift macOS 應用程式，置於選單列中，可即時顯示你已消耗的 Claude Code 配額。當 Claude Code 會話等待你的輸入時，它也會主動通知你，讓你可直接跳轉至該會話正在執行的終端機標籤頁。

為什麼重要 – Claude Code（Anthropic 的 Claude 模型 CLI）會對每會話、每週及每月的使用量設限。密切監控這些限制，可幫助你避免意外的超額費用，並防止會話默默停頓。

核心功能

功能	你能獲得的內容
使用量追蹤	顯示目前會話的使用情況、每週上限（含模型特定上限，如 Fable/Opus），以及每月超額支出。以顏色標示（綠色 < 70 %，黃色 ≥ 70 %，紅色 ≥ 90 %）提供即時健康狀態檢查。
自動刷新	每 5 分鐘查詢一次 Anthropic 的使用量端點，網路或憑證儲存區異常時會自動重試，並在電腦從睡眠中喚醒時自動刷新。
會話提醒（可選）	當有 Claude Code 會話需要你的授權或輸入時，會出現帶計數的鈴鐺圖示。可切換 macOS 通知，點擊通知或清單項目可直接跳轉至對應的 Terminal/iTerm2 標籤頁。
即時會話清單	在浮出視窗中，你可看到每個追蹤會話的狀態：需要你 🔔、正在執行 ⚙️，或已完成 ✅。
Claude Code 設定編輯器	從應用程式中可直接編輯全域的 `CLAUDE.md` 檔案，並調整 `cleanupPeriodDays`，以控制本地對話記錄的保留時間。
便利性	支援開機自動啟動、內建更新檢查，且體積輕巧（原生 Swift，無額外執行環境）。

內部運作原理

憑證 – 應用程式從 macOS 的 Keychain 讀取你的 Claude Code OAuth 憑證（密碼永遠不會離開你的機器）。
使用資料 – 它會呼叫未公開的 Anthropic 端點 api.anthropic.com/api/oauth/usage 來取得配額資訊。
會話監控 – 當啟用提醒功能時，應用程式會在 ~/.claude/settings.json 中寫入一個微小的 POSIX‑sh 鈎子。Claude Code 會為每個會話執行此鈎子，並將 JSON 狀態檔寫入 ~/.claude/claudeusage/。菜單列應用程式會監視該目錄，並相應地更新 UI 與通知。
點擊聚焦 – macOS 的輔助功能權限讓應用程式能指示 Terminal/iTerm2 選取符合會話 ID 的標籤頁，讓你可立即回應。

安裝與開始使用

下載 – 從 Releases 頁面取得最新的 ClaudeUsage.zip，解壓縮後將 ClaudeUsage.app 拖曳至 Applications 資料夾。
首次啟動 – 第一次需右鍵點選 → 開啟（macOS 會警告應用程式未簽署）。應用程式會自動尋找你的 Claude Code 憑證。
可選 – 從原始碼建置 – 克隆程式碼庫，於 Xcode 中開啟 ClaudeUsage.xcodeproj，然後按 ⌘B 建置，再按 ⌘R 執行。
啟用提醒 – 點擊菜單列浮出視窗中的齒輪圖示，開啟 當會話需要關注時提醒。應用程式會自動安裝或移除 ~/.claude/settings.json 中的鈎子。

要求

macOS 13（Ventura）或更新版本
已安裝 Claude Code CLI（npm i -g @anthropic-ai/claude-code）並登入（claude）

隱私與授權

無遙測；唯一網路呼叫是 Anthropic 的官方使用量 API。
MIT 授權原始碼 – 你可自由審查或修改。
非官方工具 – 與 Anthropic 無關；它依賴未公開的 API，未來可能變更。

由 @richhickson 製作