UsageWidget 🦊

浮動在 Mac 桌面的 AI 用量小工具：羊毛氈小狐狸頂著一塊面板，即時顯示 Claude Code 和 Codex 的短期／每週用量，每分鐘自動更新。

以 SwiftUI 打造，Swift Package 形式，不需要 Xcode 專案檔。

特色

• 零 token 成本查詢
  • Claude：claude -p "/usage" --output-format json --no-session-persistence（num_turns: 0，不消耗任何用量）
  • Codex：啟動 codex app-server 後透過 JSON-RPC 呼叫 account/rateLimits/read，直接回傳 usedPercent、視窗長度與重置時間
• 懸浮視窗：無邊框、透明背景、永遠浮在最上層，可設定連全螢幕 App 也蓋不住（.canJoinAllSpaces + .fullScreenAuxiliary）
• 圓環量表：顯示「剩餘」百分比，狀態色深淺漸層（綠 → 橘 → 紅），滑鼠停留顯示重置時間
• 三種面板背景：羊毛氈圖片（預設，九宮格拉伸保留毛邊）／系統毛玻璃／自訂顏色（含透明度染色玻璃）
• 完整設定：字體大小、文字顏色、面板背景與顏色、自訂吉祥物圖片、更新頻率、全螢幕顯示開關、一鍵回到預設
• 多語系：繁體中文、簡體中文、英文（依系統語言自動切換）

需求

• macOS 15+
• Claude Code CLI（claude）已登入
• Codex CLI（codex）已登入

下載安裝

1. 到 Releases 下載 UsageWidget.zip，解壓縮後把 UsageWidget.app 拖進「應用程式」
2. 這個 App 尚未經 Apple 公證，第一次打開時：在 App 上按右鍵 → 打開；若仍被擋，到「系統設定 → 隱私權與安全性」按「仍要打開」，或執行：

xattr -d com.apple.quarantine /Applications/UsageWidget.app

從原始碼執行

swift build -c release
.build/release/UsageWidget &

結束：點面板右下的 ⏻ 按鈕，或在面板上按右鍵選「結束」。

打包成 .app

./Scripts/make-app.sh 1.0.0

產物在 dist/UsageWidget.app 與 dist/UsageWidget.zip。腳本會：release 建置 → 組出標準 .app bundle（含 SPM 資源 bundle）→ 用小狐狸產生 AppIcon.icns → 簽章 → 壓縮。

若有 Apple Developer ID，設定環境變數後即可簽正式憑證並公證（公證後別人下載可直接雙擊開啟）：

export CODESIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)"
./Scripts/make-app.sh 1.0.0
xcrun notarytool submit dist/UsageWidget.zip --keychain-profile "AC_PROFILE" --wait
xcrun stapler staple dist/UsageWidget.app

專案結構

檔案	內容
Sources/UsageWidget/UsageWidgetApp.swift	App 進入點、懸浮視窗設定、語系 bundle 解析
Sources/UsageWidget/UsageModel.swift	@Observable 資料模型與輪詢迴圈
Sources/UsageWidget/UsageClients.swift	兩個 CLI 的查詢與解析（子程序、JSON-RPC、regex）
Sources/UsageWidget/Views.swift	面板、圓環量表、視窗行為（NSViewRepresentable）
Sources/UsageWidget/SettingsView.swift	設定視窗（@AppStorage 持久化）

技術筆記

• Codex 的 plus 方案目前只回報每週視窗時，短期圓環會顯示「–」，等伺服器重新回報 5 小時視窗後會自動出現
• 未打包成 .app 的 SPM 執行檔，main bundle 沒有語系宣告，CFBundle 會把語言鎖在開發語言——本專案用 Bundle.preferredLocalizations(from:forPreferences:) 手動挑選 .lproj 解決
• 無邊框視窗加上 .resizable styleMask 即可拖曳縮放；拖曳時把視窗寬度換算成字級，放開後視窗自動貼回內容大小