[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-77296":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":33,"readmeContent":34,"aiSummary":35,"trendingCount":14,"starSnapshotCount":14,"syncStatus":36,"lastSyncTime":37,"discoverSource":38},77296,"usage","aqua5230\u002Fusage","aqua5230","macOS menu bar app pinning Claude Code & Codex quota, tokens, and cost to your screen. Local-only, zero API calls. HTML reports, 9 themes.",null,"Python",204,37,35,0,7,26,170,33,4.74,"MIT License",false,"main",true,[25,26,27,28,29,30,31,32],"claude-code","codex","launchagent","macos","menubar","pyobjc","statusline-hook","usage-tracker","2026-06-12 02:03:42","# usage\n\n繁體中文 · [English](README.en.md)\n\n[![CI](https:\u002F\u002Fgithub.com\u002Faqua5230\u002Fusage\u002Factions\u002Fworkflows\u002Fcheck.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Faqua5230\u002Fusage\u002Factions\u002Fworkflows\u002Fcheck.yml)\n[![Latest Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Faqua5230\u002Fusage)](https:\u002F\u002Fgithub.com\u002Faqua5230\u002Fusage\u002Freleases\u002Flatest)\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.13-blue.svg)](https:\u002F\u002Fwww.python.org\u002F)\n[![Platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-macOS-lightgrey.svg)](https:\u002F\u002Fwww.apple.com\u002Fmacos\u002F)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Faqua5230\u002Fusage)](LICENSE)\n\n`usage` 是一個 macOS menu bar（螢幕右上角的選單列）小工具，把 **Claude Code 跟 Codex** 的用量同時釘在你的螢幕右上角。點開可以看到這 5 小時用了多少、這 7 天用了多少、今日 token 用量與成本估算。\n\n不呼叫 Anthropic \u002F OpenAI 的 API（接口）、也不讀 Keychain（macOS 內建的密碼保險箱），所以不會發生「自己每分鐘 ping 一次也算用量」這種事。\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fpopover.png\" alt=\"usage popover 展開時的樣子\" width=\"320\">\n\u003C\u002Fp>\n\n## 它怎麼拿到你的用量數字\n\n用量數字來自 Claude Code 跟 Codex 在你本機留下的檔案，不呼叫 Anthropic \u002F OpenAI 的 API。唯一的例外：估算 Codex 成本時需要 token 單價表，如果本機沒有快取（`~\u002F.claude\u002Fpricing_cache.json`），會嘗試從公開的 [LiteLLM 價格表](https:\u002F\u002Fgithub.com\u002FBerriAI\u002Flitellm) 下載一次並存起來，7 天後過期再抓。下載失敗的話會用內建的 fallback 價格，不影響用量百分比的顯示。首次啟動若沒快取會同步抓一次，網路慢時可能要等 ~10 秒。\n\n### Claude Code 用量\n\nusage 會幫你裝一個小腳本，這個小腳本叫做 **statusLine hook**（hook 就是「事件觸發點」，每次 Claude Code 刷新狀態列就會自動跑一次的小程式）。流程是這樣：\n\n1. Claude Code 每次更新狀態列時，會把「這 5 小時用了百分之幾、這 7 天用了百分之幾」這類資訊整理成 JSON\n2. 透過標準輸入（stdin）餵給 hook\n3. hook 把 JSON 寫進 `~\u002F.claude\u002Fusage-status.json` 這個檔\n4. usage 主程式去讀這個檔\n\n因為兩邊看的是同一份資料，**數字跟 Claude Code 自己看到的完全一樣**。\n\n```mermaid\nflowchart LR\n    A[Claude Code 主程式] -->|每次刷新狀態列\u003Cbr\u002F>把 JSON 透過 stdin 餵給 hook| B[usage-statusline.py\u003Cbr\u002F>hook 腳本]\n    B -->|寫入| C[(~\u002F.claude\u002F\u003Cbr\u002F>usage-status.json)]\n    D[usage menu bar \u002F TUI] -->|讀取| C\n    D -->|顯示| E[macOS menu bar]\n    F((Anthropic API)) -.x.- D\n    style F stroke:#c0392b,stroke-dasharray:5 5\n```\n\n讀檔的優先順序：\n\n1. `~\u002F.claude\u002Fusage-status.json` —— usage 自己 hook 寫的\n2. `~\u002F.claude\u002Fusag-status.json` —— v0.1.x legacy 自動 fallback，新使用者不會碰到\n3. `~\u002F.claude\u002Ftt-status.json` —— 備援；如果你也裝過 [token-tracker](https:\u002F\u002Fgithub.com\u002Fstormzhang\u002Ftoken-tracker)，usage 會直接共用它的狀態檔\n\n### Codex 用量\n\nCodex CLI 沒有 statusLine hook 這種機制，所以 usage 採另一條路：掃 Codex CLI 在 `~\u002F.codex\u002Fsessions\u002F` 底下留下的 `*.jsonl` 對話紀錄檔。Codex 每次對話會在紀錄裡寫入 `rate_limits`（配額資訊），usage 直接讀裡面的 5 小時跟 7 天用量百分比，不需要自己計算。今日的 token 用量跟成本則從同一份紀錄的 token 統計加總。\n\n沒裝 Codex 或沒這個資料夾的話，這部分會自動隱藏，不會影響 Claude Code 那邊的顯示。\n\n## 你需要的東西\n\n- macOS\n- Python 3.13\n- 已經裝好、登入過 Claude Code（Codex 是可選的）\n\n## 快速開始\n\n| 我是… | 怎麼用 |\n|-------|--------|\n| 一般使用者，想直接用 | [下載現成 App](#下載現成-app) |\n| 開發者，想從原始碼跑 | [建環境](#建環境) |\n| 只想先看看 UI 長什麼樣 | [預覽模式](#想先看看-ui-長什麼樣預覽模式) |\n\n## 下載現成 App\n\n到 [GitHub Releases 頁面](https:\u002F\u002Fgithub.com\u002Faqua5230\u002Fusage\u002Freleases\u002Flatest) 下載最新的 `usage.app.zip`，解壓縮後把 `usage.app` 拖到任何地方（例如 `\u002FApplications`）就能跑。\n\n⚠️ 因為沒有 Apple Developer 簽章，**第一次開啟時 macOS Gatekeeper（系統的「擋陌生程式」保全機制）會擋下來**。\n解法：在 Finder 找到 `usage.app` → 按住 Ctrl 點右鍵 → 選「打開」→ 再確認一次「打開」。之後就能直接雙擊。\n\n### 首次打開：把 hook 裝起來\n\n第一次打開 usage，如果你還沒「對接」過 Claude Code，popover 會偵測到「找不到狀態檔」，**最下面會多出一顆「立即安裝 hook」按鈕**，按一下就會幫你裝好。然後**完全結束 Claude Code（Cmd+Q）再重新打開一次**，在 usage 視窗按「立即更新」，數字就會跑出來。\n\n如果按鈕沒出現（代表 usage 已經抓到資料了，例如你之前裝過 [token-tracker](https:\u002F\u002Fgithub.com\u002Fstormzhang\u002Ftoken-tracker)），就什麼都不用做。\n\n> **備援：手動 curl 安裝**\n> 若按鈕按了沒反應、或你想用指令模式裝，打開 Terminal（終端機）貼這一行：\n>\n> ```bash\n> bash \u003C(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Faqua5230\u002Fusage\u002Fmain\u002Fscripts\u002Finstall-hook.sh)\n> ```\n\n## 拿到原始碼\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Faqua5230\u002Fusage.git\ncd usage\n```\n\n不熟 git 也可以到 [GitHub 專案頁](https:\u002F\u002Fgithub.com\u002Faqua5230\u002Fusage) 點右上角綠色的 **Code → Download ZIP**，解壓縮後 `cd` 進那個資料夾。\n\n## 建環境\n\n下面這幾行會幫你開一個**獨立的 Python 環境**（venv，virtual environment 的縮寫，就像幫這個專案開一個專用的抽屜，跟系統 Python 分開，互不干擾），然後把 usage 跟它需要的套件裝進去：\n\n```bash\npython3 -m venv .venv\nsource .venv\u002Fbin\u002Factivate\npip install -e .\n```\n\n`source .venv\u002Fbin\u002Factivate` 是「進入這個抽屜」的意思 —— 跑完之後你 terminal 提示字元前面會多一個 `(.venv)`，代表現在 Python 指令會在這個獨立環境裡跑。\n\n## 跟 Claude Code 對接（原始碼模式必跑一次）\n\n> 用 .app 的話，第一次打開直接點 popover 上的「立即安裝 hook」按鈕就好，不用跑這段。下面是給從原始碼跑 usage 的開發者用的。\n\n這個指令會做兩件事：把 usage 的 hook 腳本複製到 `~\u002F.claude\u002F` 裡，再去改 Claude Code 的設定檔，讓它每次刷新狀態列時去叫這個 hook。\n\n```bash\nsource .venv\u002Fbin\u002Factivate\npython3 main.py --setup\n```\n\n**跑完後請重開一次 Claude Code**，這樣它才會重新讀 `~\u002F.claude\u002Fsettings.json` 並刷新一次狀態列（資料這時候才會落到磁碟）。\n\nsetup 具體做了什麼：\n\n- 把 `usage_statusline.py` 複製到 `~\u002F.claude\u002Fusage-statusline.py`\n- 在 `~\u002F.claude\u002Fsettings.json` 把 `statusLine` 指向這個 hook\n- 如果你本來就有自訂的 statusLine，會自動備份到 `settings.usage.previousStatusLine`，不會被蓋掉\n\n要卸載：\n\n```bash\npython3 main.py --unsetup\n```\n\nunsetup 會把原本的 statusLine 還原回去、刪掉 hook 跟 `~\u002F.claude\u002Fusage-status.json`。\n\n## 跑起來\n\n### Menu bar 模式（預設、推薦）\n\n啟動後會在 macOS 右上角的選單列常駐，平常只顯示一行小小的百分比；點下去就會展開完整的 popover（彈出小視窗）。\n\n```bash\nsource .venv\u002Fbin\u002Factivate\npython3 main.py\n```\n\n- **選單列那行字長這樣**：`🐾 37%`；如果同時有 Codex 用量，會變成 `🐾 37% · 📜 10%`：\n\n  \u003Cimg src=\"docs\u002Fmenubar.png\" alt=\"menu bar 上方顯示樣式\" width=\"240\">\n\n- **點一下會展開 popover**，分三塊：\n  1. 上面兩張卡片分別是 Claude Code 跟 Codex，每張各有 Session（這 5 小時）跟 Weekly（這 7 天）兩條進度條，旁邊標重置倒數\n  2. 最下面那張小卡是目前速率、同步狀態、今日 token 用量與成本估算（Claude 若 log 有提供實際金額則直接顯示；Codex 成本為依 token 數估算）\n  3. 兩顆按鈕：「立即更新」、「結束」\n- **切換面板**（v0.3.0+）：在 Claude Code 卡片的右上角有一顆「⇄ 更換」按鈕（台灣面板則放在頂部標題列裡），點下去會跳出選單列出可選的面板樣式。目前內建六款：\n  - **預設**：原本兩張卡 + 速率\u002F狀態\u002F今日 的英式風格\n  - **台灣用量監控**：紅底白字、上方加一條含 TAIWAN 旗 icon 的標題列\n  - **駭客任務**（v0.3.1+）：黑底綠字數位雨動畫，Matrix 風格終端機介面\n  - **ECG 心電圖**：醫療監視器風格，LEAD A（Claude）與 LEAD B（Codex）各有一條即時 ECG 波形動畫，振幅跟著 quota 使用率變化，速率越高波形越激烈\n  - **Minimal**（v0.3.3+）：深色簡約風格，Linear \u002F Raycast 設計語言。純黑底色、圓角卡片、accent 色進度條（Claude 暖橘 \u002F Codex 青色）；頁尾卡片以左標籤 + 右數值的雙欄結構呈現速率、狀態、今日花費\n  - **手繪**（v0.3.4+）：Excalidraw 手繪塗鴉風格。珊瑚粉底色、米白卡片、粗黑邊框、卡片四角畫釘裝飾；Claude 深橘紅、Codex 深青綠，視覺輕鬆活潑\n\n  \u003Cp align=\"center\">\n    \u003Cimg src=\"docs\u002Fpopover.png\" alt=\"預設面板\" width=\"180\">\n    \u003Cimg src=\"docs\u002Fpopover-taiwan.png\" alt=\"台灣用量監控面板\" width=\"180\">\n    \u003Cimg src=\"docs\u002Fpopover-matrix.png\" alt=\"駭客任務面板\" width=\"180\">\n    \u003Cimg src=\"docs\u002Fpopover-ecg.png\" alt=\"ECG 心電圖面板\" width=\"180\">\n    \u003Cimg src=\"docs\u002Fpopover-minimal.png\" alt=\"Minimal 面板\" width=\"180\">\n    \u003Cimg src=\"docs\u002Fpopover-sketch.png\" alt=\"手繪面板\" width=\"180\">\n  \u003C\u002Fp>\n\n  選擇會記進 `NSUserDefaults`（macOS 內建的偏好設定儲存區），下次開 app 會記得上次選的面板。\n- **權限提醒**：第一次啟動時，macOS 可能會問你要不要讓它在背景跑，點「允許」就好。\n\n### 終端機 TUI 模式\n\n如果你比較喜歡留在終端機，可以用 TUI（Text-based UI，文字版的圖形介面）模式 —— 畫面全部畫在終端機裡，不開新視窗，靠不停重畫文字模擬動畫效果。會有一個 Claude 的像素藝術 logo、旋轉的 spinner、輪播 Claude Code 那套搞笑 loading 字串，以及跟 menu bar 同樣的兩條進度條：\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Ftui.png\" alt=\"usage TUI 模式畫面\" width=\"480\">\n\u003C\u002Fp>\n\n```bash\nsource .venv\u002Fbin\u002Factivate\npython3 main.py --tui\n```\n\n按 `Ctrl+C` 退出。\n\n## 開機自動啟動\n\nLaunchAgent 是 macOS 內建的背景服務管理器（負責「使用者登入後要幫忙啟動哪些程式」），可以讓 usage 在你登入時自動跑起來，不用每次手動啟動。\n\n1. **安裝**：\n   ```bash\n   .\u002Fscripts\u002Finstall-launchagent.sh\n   ```\n   這個指令會在 `~\u002FLibrary\u002FLaunchAgents\u002F` 底下放一份設定檔，然後立刻把 usage 載入起來。\n\n2. **手動啟動（測試用）**：\n   ```bash\n   launchctl start com.lollapalooza.usage\n   ```\n\n3. **查看 log**（log 就是這個服務跑的時候的「日誌」，裡面有訊息跟錯誤紀錄）：\n   - 一般訊息：`~\u002FLibrary\u002FLogs\u002Fusage\u002Fusage.log`\n   - 錯誤訊息：`~\u002FLibrary\u002FLogs\u002Fusage\u002Fusage.err.log`\n\n4. **移除**：\n   ```bash\n   .\u002Fscripts\u002Funinstall-launchagent.sh\n   ```\n\n## 想先看看 UI 長什麼樣（預覽模式）\n\n還沒裝 hook、或者只想看看介面長什麼樣，可以用假資料（mock data）跑一次：\n\n```bash\n# Menu bar 預覽\npython3 main.py --mock\n\n# TUI 預覽\npython3 main.py --tui --mock\n```\n\n## 全部可用參數\n\n- `--setup` \u002F `--unsetup`：安裝 \u002F 卸載 Claude Code statusLine hook。\n- `--tui`：強制使用終端機 TUI 模式（不開 menu bar）。\n- `--interval N`：UI 多久重新讀一次狀態檔（秒）。最小值 30，預設 60。\n- `--mock`：用假資料跑，不讀任何狀態檔。\n- `--force-group {0,1,2,3}`：強制指定速率分組（只有 TUI 模式有效）。\n\n## 除錯\n\n想看 usage 內部有沒有吞掉什麼錯誤（例如 OSError，作業系統相關錯誤），啟動時加環境變數：\n\n```bash\nUSAGE_DEBUG=1 python3 main.py\n```\n\n## 一些行為說明\n\n- usage 只讀 `~\u002F.claude\u002Fusage-status.json`、v0.1.x 留下的 `~\u002F.claude\u002Fusag-status.json`、`~\u002F.claude\u002Ftt-status.json`，以及 Codex 的 session 檔。不呼叫 Anthropic \u002F OpenAI API、不讀 Keychain。唯一會連網的情況是首次估算 Codex 成本時下載 LiteLLM 價格表（快取 7 天，離線也能用 fallback）。\n- Claude Code 沒在跑的時候，狀態檔不會更新；但因為實際用量也不會變（除非重置時間到了），所以顯示的數字仍然是有效的；重置時間過了會自動歸零。\n- 如果狀態檔超過 6 小時沒被更新過，會在狀態訊息標註「狀態檔已 N 分鐘未更新，數字可能過時」。\n\n## 常見問題排查\n\n下面的「解法」欄會分三種使用者寫，先對一下你屬於哪一種：\n\n- **.app 使用者** —— 從 GitHub Releases 下載 `usage.app.zip`、解壓後拖到 `\u002FApplications`，像一般 Mac 軟體那樣雙擊圖示用的。`.app` 就是 macOS 應用程式的副檔名（像 Windows 的 `.exe`），不用碰 Terminal、不用裝 Python。\n- **LaunchAgent 使用者** —— git clone 原始碼後，跑過 `.\u002Fscripts\u002Finstall-launchagent.sh` 讓 macOS 幫你開機自動啟動 usage 的。\n- **原始碼使用者** —— git clone 原始碼後，每次自己在 Terminal 跑 `python3 main.py` 的。\n\n| 症狀 | 原因 | 解法 |\n|------|------|------|\n| menu bar 顯示 `--` | hook 還沒裝、或 Claude Code 還沒刷新 | **.app 使用者**：點彈出視窗內的「立即安裝 hook」按鈕；**原始碼使用者**：跑 `python3 main.py --setup`。裝完都要重開一次 Claude Code |\n| 不小心按「結束」、腳印從選單列消失 | 「結束」會把整個 usage 程式關掉，要手動再開 | **.app 使用者**：按 `Cmd+Space` 叫出 Spotlight、輸入 `usage` 雙擊；或從 `\u002FApplications` 找到 `usage.app` 雙擊。**LaunchAgent 使用者**：在 Terminal 跑 `launchctl start com.lollapalooza.usage`。**從原始碼跑的**：在 Terminal 再跑一次 `python3 main.py` |\n| 狀態顯示「N 分鐘未更新」 | Claude Code 沒在跑，沒有刷新 statusLine | 打開 Claude Code 跑一下，它刷新時會自動更新 |\n| Codex 那塊空白或不顯示 | `~\u002F.codex\u002Fsessions\u002F` 不存在，或還沒有含 rate_limits 的 token_count 事件 | 用 Codex 跑一次對話，等它寫入紀錄 |\n| 今日花費是 $0.00 | 模型名稱對不上 pricing 表，或 pricing 下載 \u002F 快取失敗 | 刪掉 `~\u002F.claude\u002Fpricing_cache.json` 讓它重新抓；或設 `USAGE_DEBUG=1` 看錯誤訊息 |\n| app 雙擊打不開 | macOS Gatekeeper 擋住未簽章的 app | Finder → 找到 `usage.app` → 按住 Ctrl 右鍵 → 打開 → 確認打開 |\n\n## 打包成 .app（不開終端機就能跑）\n\n想要雙擊圖示就跑、不開終端機，可以打包成 macOS 原生 App（.app 就是 macOS 看到的圖示，本質是一個目錄，裡面把程式跟資源打包在一起）：\n\n```bash\n.\u002Fscripts\u002Fbuild_app.sh\n```\n\n跑完產物會在 `dist\u002Fusage.app`。雙擊或 `open dist\u002Fusage.app` 就能跑。\n\n每次發 GitHub Release（push 一個 `v*` 開頭的 tag 時），CI 會自動 build 並把 `usage.app.zip` 附加到 Release 頁面。\n","`usage` 是一个 macOS 菜单栏工具，用于跟踪 Claude Code 和 Codex 的使用情况。该项目通过读取本地文件来获取使用数据，避免了调用 Anthropic 或 OpenAI 的 API，从而确保隐私安全。它能够显示过去 5 小时和 7 天的使用百分比、今日 token 使用量及成本估算。对于 Claude Code，它利用 statusLine hook 机制从状态栏更新中获取数据；而对于 Codex，则通过解析对话记录文件来获取用量信息。适用于需要在 macOS 上监控 AI 编程助手使用情况的开发者，帮助他们更好地管理资源和成本。",2,"2026-06-11 03:55:18","CREATED_QUERY"]