ccusage - Claude Code 使用情況分析工具

專案概述

ccusage 是一個 CLI 工具，用於分析 Claude Code 本地 JSONL 檔案中的使用情況數據。該專案由 @ryoppippi 開發，靈感來自一篇關於追蹤 Claude Code 使用成本的文章。

主要功能

📊 多種報表類型

• 日報表: 按日期彙總 Token 使用情況和成本
• 月報表: 按月彙總 Token 使用情況和成本
• 會話報表: 按對話會話分組顯示使用情況
• 5 小時區塊報表: 基於 5 小時計費視窗的報表
• 狀態列: 用於 hooks 的緊湊狀態列（Beta 版）

🎯 強大的篩選與分析功能

• 日期篩選: 使用 --since 和 --until 按日期範圍篩選報表
• 專案分析: 按專案/實例分組，支援特定專案篩選
• 模型成本細項: 每個模型的成本細項
• 時區與本地化: 支援 UTC 時區和日語本地化格式

🎨 美觀的輸出與顯示

• 彩色表格格式顯示，具有自動響應式佈局
• 智能表格：窄終端機（<100 字元）自動緊湊模式，顯示基本欄位
• 緊湊模式：使用 --compact 標誌強制緊湊表格佈局，非常適合截圖和分享
• 增強模型顯示：模型名稱以項目符號列表顯示，提高可讀性

💰 成本追蹤功能

• 以美元顯示每日/每月/會話的成本
• 快取 Token 支援：分別追蹤和顯示快取建立和快取讀取 Token
• 離線模式：使用 --offline 在無網路連線時使用預快取定價數據（僅限 Claude 模型）

⚡ 即時監控

• 即時使用情況儀表板
• 即時監控：ccusage blocks --live

安裝與使用

快速開始（無需安裝）

由於 ccusage 具有極小的套件大小，可以直接執行而無需安裝：

# 使用 bunx（推薦，速度更快）
bunx ccusage

# 使用 npx
npx ccusage@latest

# 使用 deno（帶安全標誌）
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest

全域安裝

# 使用 npm 全域安裝
npm install -g ccusage

# 使用 bun 全域安裝
bun install -g ccusage

# 然後執行
ccusage

開發環境

# 複製儲存庫
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# 安裝依賴項
bun install

# 執行工具
bun run report [subcommand] [options]

基本用法

日報表

# 顯示所有每日使用情況
ccusage daily

# 按日期範圍篩選
ccusage daily --since 20250525 --until 20250530

# 使用自訂 Claude 資料目錄
ccusage daily --path /custom/path/to/.claude

# JSON 格式輸出
ccusage daily --json

# 每個模型的成本細項
ccusage daily --breakdown

# 使用 UTC 時區
ccusage daily --timezone UTC

# 使用日語本地化
ccusage daily --locale ja-JP

專案分析

# 按專案/實例分組
ccusage daily --instances

# 篩選至特定專案
ccusage daily --project myproject

# 組合使用
ccusage daily --instances --project myproject --json

會話報表

# 顯示所有會話
ccusage session

# 按最後活動日期篩選會話
ccusage session --since 20250525

# 組合篩選器
ccusage session --since 20250525 --until 20250530 --path /custom/path

# JSON 格式輸出
ccusage session --json

即時監控

# 即時使用情況儀表板
ccusage blocks --live

# 5 小時計費視窗
ccusage blocks

# 狀態列（Beta 版）
ccusage statusline

緊湊模式

# 強制緊湊表格模式
ccusage --compact

# 緊湊月報表
ccusage monthly --compact

命令選項

所有命令皆支援以下選項：

• -s, --since <date>: 從日期篩選（YYYYMMDD 格式）
• -u, --until <date>: 篩選至日期（YYYYMMDD 格式）
• -p, --path <path>: Claude 資料目錄的自訂路徑（預設：~/.claude）
• -j, --json: 以 JSON 格式而非表格輸出結果
• -h, --help: 顯示幫助資訊
• -v, --version: 顯示版本

輸出範例

日報表輸出

╭──────────────────────────────────────────╮
│                                          │
│ Claude Code Token Usage Report - Daily  │
│                                          │
╰──────────────────────────────────────────╯
┌──────────────────┬──────────────┬───────────────┬──────────────┬────────────┐
│ Date             │ Input Tokens │ Output Tokens │ Total Tokens │ Cost (USD) │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ 2025-05-30       │ 277          │ 31,456        │ 31,733       │ $17.45     │
│ 2025-05-29       │ 959          │ 39,662        │ 40,621       │ $16.37     │
│ 2025-05-28       │ 155          │ 21,693        │ 21,848       │ $8.33      │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ Total            │ 11,174       │ 720,366       │ 731,540      │ $336.17    │
└──────────────────┴──────────────┴───────────────┴──────────────┴────────────┘

會話報表輸出

╭───────────────────────────────────────────────╮
│                                               │
│ Claude Code Token Usage Report - By Session  │
│                                               │
╰───────────────────────────────────────────────╯
┌──────────────────────────────┬──────────────┬───────────────┬──────────────┬────────────┬───────────────┐
│ Project / Session            │ Input Tokens │ Output Tokens │ Total Tokens │ Cost (USD) │ Last Activity │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ my-project                   │ 2,775        │ 186,645       │ 189,420      │ $98.40     │ 2025-05-26    │
│ └─ session-abc123...         │              │               │              │            │               │
│ another-project              │ 1,063        │ 41,421        │ 42,484       │ $20.08     │ 2025-05-29    │
│ └─ session-def456...         │              │               │              │            │               │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ Total                        │ 11,174       │ 720,445       │ 731,619      │ $336.38    │               │
└──────────────────────────────┴──────────────┴───────────────┴──────────────┴────────────┴───────────────┘

技術架構

依賴要求

• Bun 執行環境
• Claude Code 使用歷史檔案（~/.claude/projects/**/*.jsonl）

專案結構

ccusage/
├── commands/
│   ├── daily.ts        # 日報表命令
│   └── session.ts      # 會話報表命令
├── data-loader.ts      # JSONL 資料載入邏輯
├── index.ts           # CLI 入口點
├── logger.ts          # 日誌配置
├── utils.ts           # 共享工具
└── package.json

開發與測試

# 執行測試
bun test

# 型別檢查
bun run typecheck

# 程式碼檢查
bun run lint

# 格式化程式碼
bun run format

整合功能

🔌 MCP 整合

內建模型上下文協議伺服器，用於與其他工具整合

總結

ccusage 是一個功能強大且易於使用的 CLI 工具，專為 Claude Code 使用者設計，用於分析和追蹤 Token 使用情況及相關成本。其輕量級設計、豐富的功能集和美觀的輸出使其成為希望最佳化 Claude Code 使用並管理成本的開發者的理想選擇。