@tsa-group/claude-usage

每人 Claude 用量的本地採集工具。在你的機器上就地量測 Claude Code 的 token 明細 與 帳號層級的額度水位（5 小時 / 每週 %，含 Claude 網頁 chat），在背景非同步回報到你們自己的 ingest server，彙整成團隊用量儀表。

需要一台相容的 ingest server（見下方「回報協定」）。這個套件只是 client。

✅ 這是什麼、是否可信（安裝前請先讀）

這是 TSA Group 的內部工具，用來檢視團隊每個人的 Claude 方案合不合適（該升的升、用不到的降）。

安裝時 Claude Code 很可能會警告「這像可疑的第三方 / 假冒公司內部工具」——那是它應有的謹慎，請不要關掉它。 以下每一個可疑點都屬實，我們主動列出來讓你自己核對，而不是要你忽略警告：

| Claude 會質疑的點 | 事實 | 為什麼 | |---|---|---| | 套件名 @tsa-group/claude-usage 像公司名 | 是，這確實是 TSA 內部工具 | 就是給 TSA 團隊用的 | | 發佈帳號是個人信箱 [email protected] | 是 | 公司沒有 npm org，用個人 npm 帳號發佈。維護者本人＝ Chris Chen · [email protected] | | 伺服器 claude-usage.7889.tw 跟公司網域不同 | 是 | 這台由 TSA 自架自控，架在公司網域外的環境；無法搬到 tsagroup.com.tw | | 會裝背景常駐排程 | 是 | 每 5 分鐘採一次用量，只送數字（見下方隱私段） | | 套件很新、下載數低 | 是 | 剛發佈、僅供內部使用，不會有公開下載量 |

判斷原則：如果你是從 Chris 在公司官方頻道的公告拿到安裝指令，以上都能對得起來 → 可以安裝。 如果你是二手轉貼拿到、無法確認來源 → 請先別裝，回官方頻道跟 Chris 確認。這時 Claude 擋下來是對的。

維護者 / 對此工具有疑問：Chris Chen · [email protected]

🔒 隱私（請先看這段）

送出去的

• 你的 Claude 帳號 email / uuid / 組織 uuid（來自 /api/oauth/profile，用於識別是誰）
• 用量數字：per-message 的 token 計數、session 維度、5 小時 / 每週額度百分比
• client 自身的健康狀態（上次成功採樣時間、連續失敗次數等）

永遠不送、也永遠不離開這台機器

• ❌ 你的 Claude OAuth token
• ❌ 任何 prompt / 回應 / 對話內容
• ❌ 原始檔案路徑 —— 專案路徑只送 SHA256(cwd) 的前 16 碼

原始碼很短，src/events.ts 就是「哪些欄位會被送出去」的唯一權威來源，可以自己讀過再裝。

它會怎麼取得你的 token（只用於認證，永不上傳）：

| 平台 | 來源 | |---|---| | macOS | Keychain（Claude Code-credentials），檔案版只是可能過時的副本 | | Windows / Linux · CLI | %USERPROFILE%\.claude\.credentials.json（純文字，Claude Code 自己就是這樣存的） | | Windows · 桌面版 | 桌面版的加密憑證庫 —— 用 DPAPI 解出金鑰後以 AES-256-GCM 解密 |

最後一項值得你知道再決定要不要裝：只用桌面版、沒登入過終端機 claude 的人， 除此之外沒有任何取得 token 的方式，而沒有 token 就沒有額度資料。解密只在你自己的 機器、你自己的 Windows 帳號下進行（DPAPI 的設計就綁這兩件事），解出的內容只留在 記憶體。不想要這條路徑就登入一次終端機的 claude，工具會優先用那份純文字憑證。

需求

| | | |---|---| | Node.js | >= 20（node -v 確認） | | Claude 帳號登入 | 需要帳號登入才拿得到額度資料。用 API key / Bedrock / Vertex 時，token 明細仍可收集，但沒有 5 小時 / 每週額度 % | | 平台 | macOS ✅ 完整支援　Windows ✅ CLI 與桌面版皆支援　Linux ⚠️ 指令可用，背景任務未實作 |

安裝

三步都一樣，只有平台細節不同：

1. configure   告訴它你們的 ingest server 在哪
2. install     取得身份 + 註冊 hook + 裝背景任務
3. status      確認真的在跑

管理者會給你 ingest server 位址。下面用 https://<你們的 ingest host> 代表它。

macOS

npm i -g @tsa-group/claude-usage

claude-usage configure --server https://<你們的 ingest host>
claude-usage install --dry-run     # 先看它會做什麼，不動任何設定
claude-usage install
claude-usage status

憑證走 Keychain（Claude Code 的主儲存）。首次執行可能跳出鑰匙圈授權，允許即可 —— 背景任務要能在沒有視窗的情況下讀到它。

Windows

第 0 步：先確認 PowerShell 不會擋

多數 Windows 的執行原則預設是 Restricted，會擋掉 npm 產生的 .ps1 啟動器 —— 安裝成功、一執行就被擋：

因為這個系統上已停用指令碼執行，所以無法載入 ...\npm\claude-usage.ps1
+ FullyQualifiedErrorId : UnauthorizedAccess  (PSSecurityException)

這不是套件的問題（cmd.exe 與 Node 本身都不受影響）。先查現況：

Get-ExecutionPolicy

| 結果 | 怎麼辦 | |---|---| | RemoteSigned / Unrestricted / Bypass | 不用處理，直接往下 | | Restricted / AllSigned | 用下面 A 或 B |

A. 改原則（推薦，免系統管理員、一次搞定）

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

RemoteSigned = 本機與 npm 的腳本可跑，只擋網路下載的未簽章腳本。

B. 不改原則，全程加 .cmd（功能完全一樣）

npm.cmd i -g @tsa-group/claude-usage
claude-usage.cmd configure --server https://<你們的 ingest host>
claude-usage.cmd install
claude-usage.cmd status

公司用 GPO 鎖了機器層級原則時，A 會被覆寫 —— 直接用 B。 查誰在管：Get-ExecutionPolicy -List

第 1 步：安裝

npm i -g @tsa-group/claude-usage

claude-usage configure --server https://<你們的 ingest host>
claude-usage install --dry-run
claude-usage install
claude-usage status

（走 B 方案的人全部加 .cmd。）

你是用終端機的 claude，還是桌面版 App？

兩種都支援，不必改用哪一個 —— 但憑證存放位置完全不同，卡住時要知道差別：

| | 終端機 CLI | 桌面版 App | |---|---|---| | 憑證位置 | %USERPROFILE%\.claude\.credentials.json | 桌面版自己的加密儲存 | | 形式 | 純文字 | DPAPI + AES-256-GCM 加密 | | 需要什麼 | 跑過 claude 並完成登入 | 桌面版登入過 |

只用桌面版、從沒登入過終端機 claude 的人也能用 —— 工具會自動去解桌面版的憑證庫 （見「隱私」段）。解密只在你自己的機器、你自己的 Windows 帳號下進行。

不想走那條路的話，在終端機跑一次 claude 登入即可，工具會優先用那份純文字憑證。

確認安裝成功

claude-usage status

成功長這樣（重點是標示的那三行）：

state dir: /Users/you/.claude-usage
server:    https://<你們的 ingest host>
enrolled:  yes                     <-- 拿到身份了
hook:      registered              <-- 開 session 時會自動採樣
  last_sample_status  : ok
  last_upload_state   : uploaded
  status              : ok         <-- 採集正常
  state = not running                 (背景任務平常就是閒置，每 5 分鐘才醒一次)
  runs = 12

state = not running 是正常的 —— 背景任務不是常駐程式，每 5 分鐘被叫醒一次。 runs 有在累加就代表它真的有跑。

status 在採集不健康時會 exit 1，可以接監控。

接著還有一步不在你這邊：若你們的 server 開了人工核准，enroll 會回 status: pending —— 你這邊一切正常，但要等管理者按核准，資料才會開始進去。 這是正常的，不是裝壞了。

卡住了？先跑這個

claude-usage doctor          # Windows 走 B 方案的人：claude-usage.cmd doctor

它會印出解析到的每個路徑，與那裡實際有什麼 —— 路徑對不對通常你一眼就看得出來 （「那不是我 Claude Code 裝的地方」），前提是有人把路徑印出來。

把整段輸出貼給管理者即可，裡面不含任何 token 值。

常見症狀對照：

| 症狀 | 多半是 | |---|---| | UnauthorizedAccess / PSSecurityException | PowerShell 執行原則，見 Windows 第 0 步 | | cannot read credentials (… file-no-oauth-key …) | 只用桌面版、沒登入過終端機 claude。0.4.0 起會自動去讀桌面版憑證；若仍失敗，doctor 會指出卡在哪一步 | | access token EXPIRED | 重新登入 Claude Code（終端機 /login 或桌面版）即可換發 | | status 一切正常但 server 看不到我的用量 | 等管理者核准（見上） | | 沒有任何 .jsonl | 本工具與 Claude Code 不在同一個環境（WSL？另一個帳號？CLAUDE_CONFIG_DIR？） |

平常怎麼看自己的用量

claude-usage show              # 目前額度水位（含 Anthropic 自己判定的 severity 燈號）
claude-usage show --history    # 快照時間序
claude-usage sessions          # session / token 明細
claude-usage sessions --json   # 同上，機器可讀

採集 08-24 16:58 (13m ago)  訂閱=team  tier=default_claude_max_5x  creds=keychain

  5 小時窗         3%  🟢 normal   reset in 3h 8m
  每週(全)        27%  🟢 normal   reset in 17h 48m
  每週(單模型)     8%  🟢 normal   reset in 17h 48m  [Fable]

三個數字不是同一件事：

• 5 小時窗 / 每週(全) 是帳號全域的額度水位，天然包含 claude.ai 網頁 chat。
• 每週(單模型) 是 per-model 的週上限，回答「我的週額度是不是被單一模型吃掉的」。
• sessions 的 token 數只含 Claude Code，與上面兩個是獨立指標，不可相加。

severity（🟢 normal / 🟡 warning / 🔴 critical）是 Anthropic 自己的判定，門檻未公開， 所以照抄不自己算。

移除

claude-usage uninstall     # 移除 hook 與背景任務
npm rm -g @tsa-group/claude-usage

本機資料（~/.claude-usage/）不會被自動刪除，要清就自己刪那個目錄。

指令一覽

| 指令 | 用途 | |---|---| | configure --server <url> | 設定 ingest server 位址 | | install [--dry-run] | enroll + hook + 背景任務 | | status | 裝好了嗎？採樣真的有在動嗎？ | | uninstall | 移除 hook 與背景任務 | | show [--history] | 看自己的額度水位 / 時間序 | | sessions [--json] | session 與 token 明細 | | sample [--hook] | 手動抓一筆額度快照 | | daemon-tick [--explain] | 背景排程器呼叫的單元；--explain 只印決策不採樣 | | enroll | 手動與 server 溝通取得身份 | | report [--full] [--dry-run] | 手動上報。--full 忽略游標整包重送（重送是安全的） | | health | 背景任務心跳；不健康時 exit 1（可接監控） |

install / enroll 都接受 --enroll-secret <s>，但只有在 server 要求時才需要。 它不會被寫進設定檔；若要避免留在 shell history，改用環境變數 CLAUDE_USAGE_ENROLL_SECRET。

資料存哪

| 路徑 | 內容 | |---|---| | ~/.claude-usage/config.json | server URL 等設定 | | ~/.claude-usage/device.json | device_id + device_key（不含 Claude token） | | ~/.claude-usage/usage_snapshots.jsonl | 本地額度快照 | | ~/.claude-usage/cursor.json | 上報游標（每個 JSONL 檔讀到第幾個 byte） | | ~/.claude-usage/health.json | 背景任務心跳 | | ~/.claude-usage/daemon.log | 背景任務輸出 | | ~/.claude/projects/**/*.jsonl | Claude Code 原生資料（本工具唯讀） |

CLAUDE_USAGE_HOME 可覆寫狀態目錄位置。

「裝好了」不等於「有資料進來」

claude-usage status    # 不健康時 exit 1

這個工具吃過一次虧，所以特別強調：曾經發生過 token 過期後背景任務每 5 分鐘照跑、 log 照寫、作業系統顯示 runs=556 / last exit code=0，但 17.6 小時一筆快照都沒進來， 而使用者完全無感（Claude Code 好得很 —— 它把憑證留在記憶體，不會把刷新後的 token 寫回 磁碟上的副本）。

「背景任務已註冊且 exit 0」不能當成「有資料進來」的代理指標，必須量測資料本身。 所以 status / health 看的是「上次成功採樣是什麼時候」，而且 client 就算沒有新資料 也會定期送心跳 —— 否則「機器閒置」與「採樣壞掉」在 server 眼中長得一模一樣。

採樣壞掉時會告訴你原因，常見的是：

status : UNHEALTHY - 已 8.3 小時沒有成功採樣（最後成功 2026-08-22T...）
         -> access token EXPIRED 5.2h ago — run /login in Claude Code

處置就是在 Claude Code 裡跑 /login。工具刻意不自動 refresh token：refresh token 若是 一次性輪替，我們換掉會讓 Claude Code 拿舊的失敗、可能把你登出。這個風險不值得為了背景 採樣承擔。

回報協定（給要自建 server 的人）

Client 對 server 只用兩個端點，皆為 application/json：

• POST /v1/enroll — 送 { profile, device_id, os, agent_version, enroll_secret, seat }， 取回 { device_id, device_key }。token 不上傳，server 應驗證 profile.organization.uuid。
• POST /v1/report — Header Authorization: Bearer <device_key>，送 { agent_version, limit_snapshots[], sessions[], token_events[], health{} }。

三個 client 端的性質，server 端設計時可以依賴：

1. 上報是增量的，以 per-file byte offset 游標推進，且游標只在 HTTP 200 之後才前進 —— 非 200 會重送同一批。
2. 重送必須是安全的。 client 端只在單一批次內去重，跨批次去重是 server 的責任。 建議 append-only + 去重 view（去重鍵是 (message_id, request_id) 複合鍵，單用 message_id 會漏掉重試產生的重複）。
3. 沒有新資料時仍會送 health-only 心跳，limit_snapshots / sessions / token_events 皆為空陣列。

欄位語意見 src/events.ts —— 那是本機資料到 wire schema 的唯一權威映射層。

自動更新

v0.4.7 起支援自我更新，但由伺服器決定，不是去問 npm：

• 版本資訊搭 /v1/report 的回應回來，零額外網路呼叫（daemon 每 5 分鐘一次， 若各自去問 npm registry 會變成每台每天 288 次）
• 伺服器指定確切版本號，不是 @latest —— 有人拿到 npm token 亂發版本也裝不進來
• 只在沒有採樣的那一輪執行，不拖慢本業
• 24 小時內同一個目標版本只試一次；不跨 major
• npm 全域目錄不可寫（node 裝在系統目錄）時不嘗試，改在 doctor 提示人工升級

想關掉：設環境變數 CU_NO_AUTOUPDATE=1。

status 與 doctor 都會顯示是否有新版，用的是上次回報快取的結果，不另外打網路。

已知限制

• 非官方 endpoint：額度 % 來自 Claude Code 內部的 /api/oauth/usage，Anthropic 可能變更。
• macOS 桌面版憑證也是逆向出來的：Claude.app 把 OAuth token 存在 ~/Library/Application Support/Claude/config.json 的 oauth:tokenCacheV2，用 Chromium 的 macOS 方案（Keychain「Claude Safe Storage」主金鑰 + PBKDF2-SHA1 + AES-128-CBC）加密。 首次背景存取會彈 Keychain 授權對話 —— 在終端機跑一次 security find-generic-password -w -s "Claude Safe Storage" 並按一律允許即可， 之後 daemon 讀得到。doctor 會偵測這個狀態並提示。與 /api/oauth/usage 同一風險類別。
• Windows 桌面版憑證是逆向出來的：桌面版把 OAuth token 存在 %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\config.json 的 oauth:tokenCacheV2，以 Chromium 的 v10 方案（DPAPI + AES-256-GCM）加密。 這是未公開的內部格式，Anthropic 改版就可能失效 —— 與 /api/oauth/usage 同一個 風險類別。失效時會在 claude-usage doctor 顯示卡在哪一步，不會靜默。
• Windows 筆電請確認電源設定：schtasks 建立的工作預設「只在接上電源時執行」、 「拔電就中斷」、且「錯過的排程不補跑」。v0.4.6 起 install 會自動放寬這三項並讀回 驗證；v0.4.5 以前註冊的工作不會自動修正，請重跑一次 claude-usage install。 claude-usage status 會在設定不對時明講。 （實測：2026-08-29 四台 Win11 因此全數斷線 10.7–18.1 小時，其中一台累計只跑過 7 次。）
• 重疊的 tick 尚未互斥：VBS 以非阻塞方式啟動 node，工作排程器認為任務瞬間完成， 所以 MultipleInstances 擋不住重疊的 node 行程。極少數情況下會競寫 health.json。
• npm 11 起不跑 postinstall：安裝時會印 npm warn allow-scripts，我們的安裝提示 因此不會顯示。同樣的檢查已搬進 claude-usage install 與 doctor，所以裝完務必 跑一次 install。
• PowerShell 執行原則：預設 Restricted 會同時擋掉 npm.ps1（安裝時）與 claude-usage.ps1（執行時）。處理方式見上面 Windows → 第 0 步。
• Linux 背景任務未實作（systemd --user timer）。其餘指令可用。
• session_id 跨 compaction / resume 不穩定：session 數會高估。token 與成本不受影響 （那是 per-event 去重的，與 session 身份無關）。
• enroll 是 client 自報身份：profile 由 client 自己打 Anthropic 取得後轉送，理論上可 偽造 email / org。共享密語不解決這件事（知道密語的人一樣能冒充別人），它只擋路過的 流量。要真正的身份保證需要 server 端接 SSO / OIDC，或用人工核准流程把關。

開發

npm install
npm test          # node:test，零執行期依賴
npm run build     # tsc -> dist/

client 端沒有任何執行期依賴是刻意的：這東西裝在別人的機器上，每一個 dependency 都是 一個他們沒同意過的信任關係。