ccusage-team

Claude Code 使用量分析工具，支援即時團隊監控與協作

npm version NPM Downloads GitHub stars

繁體中文 | 🇺🇸 English

> 基於 @ryoppippi 出色的 [ccusage](https://github.com/ryoppippi/ccusage) 延伸開發，新增團隊協作、即時監控與背景同步功能。 --- ## 目錄 - [系統需求](#系統需求) - [安裝](#安裝) - [Linux / macOS](#linux--macos) - [Windows（原生）](#windows原生) - [Windows + WSL](#windows--wsl) - [快速開始](#快速開始) - [指令參考](#指令參考) - [團隊功能](#團隊功能) - [建立團隊](#建立團隊) - [加入團隊](#加入團隊) - [即時監控](#即時監控) - [背景同步 Daemon](#背景同步-daemon) - [設定](#設定) - [常見問題排查](#常見問題排查) --- ## 系統需求 | 項目 | 需求 | |------|------| | Node.js | 20.19.4 以上 | | Claude Code | 任意版本 | | 作業系統 | Linux、macOS、Windows 10/11（原生或 WSL） | | 網路 | 團隊功能需要；本機報告可離線使用 | --- ## 安裝 ### Linux / macOS ```bash npm install -g ccusage-team ``` 確認安裝成功： ```bash ccusage-team --version ccusage-team daily ``` --- ### Windows（原生） 在 **PowerShell** 或**命令提示字元**中執行： ```powershell npm install -g ccusage-team ``` 確認安裝成功： ```powershell ccusage-team --version ccusage-team daily ``` **Windows 使用者注意**：Claude Code 將資料儲存在 `%APPDATA%\Claude\projects`，工具會自動偵測此路徑。若偵測失敗，請手動指定： ```powershell # 當前工作階段有效 $env:CLAUDE_CONFIG_DIR = "$env:APPDATA\Claude" ccusage-team daily # 永久設定（加入 PowerShell 設定檔） [System.Environment]::SetEnvironmentVariable("CLAUDE_CONFIG_DIR", "$env:APPDATA\Claude", "User") ``` --- ### Windows + WSL 提供兩種方案： **方案 A — 在 WSL 內安裝（推薦，尤其需要使用團隊同步功能）** 開啟 WSL 終端機執行安裝： ```bash # 在 WSL 內 npm install -g ccusage-team ``` 由於 Claude Code 在 Windows 原生執行（資料儲存於 Windows 的 `%APPDATA%\Claude`），需要告訴工具去哪裡尋找資料。**WSL 使用者名稱可能與 Windows 使用者名稱不同**，請確認： ```bash # 查看 Windows 的使用者資料夾，找到您的 Windows 使用者名稱 ls /mnt/c/Users/ # 設定資料路徑（將 替換為您的 Windows 使用者名稱） export CLAUDE_CONFIG_DIR=/mnt/c/Users//AppData/Roaming/Claude # 加入 ~/.bashrc 或 ~/.zshrc 以持久保存 echo 'export CLAUDE_CONFIG_DIR=/mnt/c/Users//AppData/Roaming/Claude' >> ~/.bashrc source ~/.bashrc # 確認資料可正確讀取 ccusage-team daily ``` **方案 B — 在 Windows 原生安裝，透過 WSL 互通呼叫** ```powershell # 在 PowerShell 中 npm install -g ccusage-team ``` 然後從 WSL 呼叫： ```bash # 在 WSL 中呼叫 Windows 安裝的指令 ccusage-team.cmd daily ``` > 若需要使用背景同步 daemon，建議使用方案 A（WSL 原生安裝），因為 Linux 環境下的程序管理更為可靠。 --- ## 快速開始 安裝後可使用完整指令名稱或簡短別名 `ccul`： ```bash # 查看今日使用量 ccusage-team daily # 互動式選單（最簡單的入門方式） ccusage-team ``` --- ## 指令參考 ### 使用量報告 ```bash ccusage-team daily # 每日 token 使用量與費用 ccusage-team monthly # 月度彙總報告 ccusage-team session # 依對話工作階段統計 ccusage-team blocks # 5 小時計費視窗 # 簡短別名 ccul daily ccul monthly ccul session ccul blocks ``` ### 報告選項 ```bash ccul daily --json # 以 JSON 格式輸出 ccul daily --mode calculate # 強制從 token 重新計算費用 ccul daily --mode display # 只使用預先計算的費用 ccul daily --since 20250101 # 從指定日期起篩選（格式：YYYYMMDD） ccul blocks --active # 只顯示目前活躍的計費區塊 ccul blocks --recent # 顯示最近 3 天的計費區塊 ccul session --project myproject # 依專案名稱篩選 ``` ### 互動式選單 ```bash ccusage-team # 開啟完整互動式選單 ``` 互動式選單提供所有功能的引導介面，適合初次使用者。 ### 團隊管理 ```bash ccul team create "團隊名稱" # 建立新團隊 ccul team join <邀請碼> # 使用 6 位邀請碼加入團隊 ccul team list # 列出您所屬的所有團隊 ccul team members [團隊名稱] # 顯示團隊成員 ccul team usage [團隊名稱] # 顯示團隊使用量統計 ccul team live [團隊名稱] # 開啟即時團隊監控儀表板 ccul team leave # 離開目前的團隊 ``` ### 背景同步 Daemon ```bash ccul team sync start [團隊名稱] # 啟動背景同步 daemon ccul team sync stop [團隊名稱] # 停止 daemon ccul team sync restart [團隊名稱] # 重新啟動 daemon ccul team sync status [團隊名稱] # 查看 daemon 狀態與上次同步資訊 ccul team sync once [團隊名稱] # 執行一次性同步後退出 ccul team sync logs [團隊名稱] # 查看 daemon 日誌輸出 ``` ### 其他指令 ```bash ccusage-team update # 檢查並套用更新 ccusage-team mcp # 啟動 MCP 伺服器（stdio） ccusage-team mcp --type http --port 8080 # 啟動 MCP 伺服器（HTTP） ``` --- ## 團隊功能 ### 建立團隊 由團隊建立者執行，完成後將邀請碼分享給成員。 **步驟一 — 建立團隊：** ```bash ccul team create "我的團隊" ``` 輸出範例： ``` ✅ Team created successfully Team name: 我的團隊 Invite code: ABC123 Share this code with your teammates! ``` **步驟二 — 將邀請碼**（本例為 `ABC123`）分享給所有團隊成員。 --- ### 加入團隊 每位成員在自己的電腦上執行： ```bash ccul team join ABC123 ``` 系統會詢問您的顯示名稱。按 Enter 接受自動偵測到的系統使用者名稱，或輸入自訂名稱： ``` Invite Code: ABC123 User Name: vic ← 按 Enter 接受，或輸入新名稱 ``` 加入後，啟動同步 daemon 讓使用資料自動上傳： ```bash ccul team sync start ``` --- ### 即時監控 任何成員均可開啟即時監控儀表板： ```bash ccul team live ``` 儀表板每 5 秒自動重整，顯示： - **Usage / Current window（使用情況 / 當前視窗期）** — 您目前 5 小時計費區塊的 token 使用量 - **Member status（成員狀態，最近 10 天）** — 每位成員的累計 token、費用與活躍狀態 - **Team total（團隊總計）** — 全體成員的彙總 token 與費用 按 `q` 或 `Ctrl+C` 退出。 --- ### 背景同步 Daemon Daemon 在背景持續執行，自動將您的本機使用資料上傳至團隊資料庫。**若未啟動 daemon，您的使用量將不會出現在團隊統計中。** **啟動 daemon：** ```bash ccul team sync start # 或明確指定團隊名稱 ccul team sync start "我的團隊" ``` **查看 daemon 狀態：** ```bash ccul team sync status ``` 輸出範例： ``` 📊 Sync daemon status — 我的團隊 Daemon: Running / 執行中 (PID 12345) Last sync / 上次同步: 2026-04-24 10:30:15 Synced blocks / 已同步區塊: 47 Log file / 日誌: ~/.config/ccusage-team/daemons/.log ``` **查看 daemon 日誌**（排查問題最有用）： ```bash ccul team sync logs # 顯示更多行 ccul team sync logs -n 100 ``` **停止 daemon：** ```bash ccul team sync stop ``` **執行一次性同步（不啟動常駐 daemon）：** ```bash ccul team sync once ``` --- ## 設定 ### 環境變數 | 變數 | 說明 | 範例 | |------|------|------| | `CLAUDE_CONFIG_DIR` | Claude 資料目錄路徑 | `/mnt/c/Users/vic/AppData/Roaming/Claude` | | `CLICKHOUSE_HOST` | ClickHouse 伺服器 URL | `https://your-server.com:8443` | | `CLICKHOUSE_DATABASE` | 資料庫名稱 | `ccusage` | | `CLICKHOUSE_USERNAME` | 資料庫使用者名稱 | `default` | | `CLICKHOUSE_PASSWORD` | 資料庫密碼 | `your-password` | ### 多個 Claude 資料目錄 若您在多處使用 Claude Code（例如同時有 WSL 和 Windows 原生），可用逗號分隔多個路徑： ```bash export CLAUDE_CONFIG_DIR="/home/vic/.config/claude,/mnt/c/Users/vic/AppData/Roaming/Claude" ``` --- ## 常見問題排查 ### 出現「您還沒有加入任何團隊」 工具無法找到您的團隊成員資格。使用者 ID 是根據您的使用者名稱和機器資訊產生的。 請確認： 1. 您已在**這台機器**上，以**正確的使用者名稱**加入團隊 2. 執行 `ccul team list` 確認是否能偵測到成員資格 3. 若曾以不同使用者名稱加入，請重新加入：`ccul team join <邀請碼>` --- ### Daemon 顯示執行中，但團隊統計沒有資料 Daemon 程序可能已靜默崩潰，留下過時的 PID 檔案。**請先查看日誌：** ```bash ccul team sync logs ``` **若日誌顯示 `ERROR: Cannot find Claude data path`（找不到 Claude 資料路徑）：** 未找到 Claude 資料目錄。請手動指定路徑： ```bash # WSL 使用者 export CLAUDE_CONFIG_DIR=/mnt/c/Users/<您的Windows使用者名稱>/AppData/Roaming/Claude # 重啟 daemon ccul team sync stop ccul team sync start ``` **若日誌顯示 `sync ok — ... N failed`（N 個區塊同步失敗）：** 資料找到了，但寫入資料庫失敗。請確認 ClickHouse 連線設定： ```bash # 確認環境變數已設定 echo $CLICKHOUSE_HOST # 執行一次性同步查看詳細錯誤 ccul team sync once ``` **若日誌顯示 `sync ok — ... 0 total blocks`（共 0 個區塊）：** 表示沒有找到本機使用資料。先確認基本報告能否正常執行： ```bash ccusage-team daily ``` 若 `daily` 也沒有資料，表示 `CLAUDE_CONFIG_DIR` 指向了錯誤的路徑。 --- ### 「No valid Claude data directories found」（找不到有效的 Claude 資料目錄） ```bash # WSL 使用者：確認 Windows 資料路徑存在 ls /mnt/c/Users/<您的Windows使用者名稱>/AppData/Roaming/Claude/projects # Windows 原生使用者（PowerShell） dir "$env:APPDATA\Claude\projects" # 找到正確路徑後，設定環境變數 export CLAUDE_CONFIG_DIR=/mnt/c/Users/<您的Windows使用者名稱>/AppData/Roaming/Claude ``` --- ### Windows 使用者名稱無法自動偵測 工具會依序嘗試 `USER` → `USERNAME` → `os.userInfo()` 來偵測使用者名稱。若全部失敗，可透過互動式選單手動輸入： ```bash ccusage-team # 選擇：團隊管理 → 加入團隊 # 系統會顯示偵測到的名稱，您可以直接修改 ``` 或在指令中直接指定： ```bash ccul team sync start -u 您的名稱 ``` --- ### 如何確認同步是否正常運作 執行以下指令進行完整診斷： ```bash # 1. 確認本機資料可正常讀取 ccusage-team daily # 2. 執行一次性同步，觀察輸出 ccul team sync once # 3. 確認 daemon 狀態 ccul team sync status # 4. 查看 daemon 日誌（最近 50 行） ccul team sync logs # 5. 若一切正常，重啟 daemon 確保是最新版本 ccul team sync restart ``` --- ## 運作原理 1. Claude Code 將使用資料寫入 JSONL 檔案，位於 `~/.config/claude/projects/`（Linux/macOS）或 `%APPDATA%\Claude\projects\`（Windows） 2. `ccusage-team` 讀取這些 JSONL 檔案來產生報告 3. 同步 daemon 定期讀取 JSONL 檔案，將工作階段區塊上傳至共用的 ClickHouse 資料庫 4. `team live` 和 `team usage` 查詢此資料庫，顯示全團隊的統計資料 --- ## 致謝 - **[@ryoppippi](https://github.com/ryoppippi)** — 原始 [ccusage](https://github.com/ryoppippi/ccusage) 的創作者 - **Claude Code 社群** — 提供出色的 CLI 工具 ## 授權條款 [MIT](LICENSE) © [Calderic](https://github.com/Calderic)