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使用和管理成本的开发者的理想选择。