ccusage
从本地数据统计各类编码 Agent CLI 的 token 用量与费用，一键生成日/周/月/会话报表。
- Star 数
- ★ 19k
- 最近更新
- 今天
- License
- NOASSERTION
- 主语言
- Rust
- FA 评分
- 67/100 · 存在缺口
30 秒速览
- 可在哪里用
- 通用 · 跨平台Codex · Claude CodeChatGPT（部分支持）
- 开始前需要
- 典型场景
- 个人开发者想弄清自己这个月在 Claude Code 和 Codex 上各花了多少，需要按日/月查看 token 与美元成本。
- 主要局限
- 只读取本地数据，统计结果取决于各 CLI 是否已在本地留下用量记录，无法覆盖团队或云端账户的完整消费。
- 源码审查
- 67/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
ccusage 是一个命令行工具，从编码 Agent CLI 的本地数据文件中读取 token 用量，并汇总为每日、每周、每月和按会话的报告。它支持 Claude Code、Codex、OpenCode、Amp、Droid、Codebuff、Hermes Agent、pi-agent、Goose、OpenClaw、Kilo、Kimi、Qwen、GitHub Copilot CLI、Gemini CLI、Antigravity、Grok Build CLI 和 ZCode 等来源，可用 ccusage daily、ccusage weekly、ccusage monthly、ccusage session 将全部检测到的来源合并为一张报表。除表格输出外，它还支持 --json 结构化导出、--no-cost 隐藏费用、--since/--until/--last 日期过滤、--timezone 时区分组以及 ccusage.json 自定义价格覆盖。它以 npx/bunx 一次性运行的方式交付，无需全局安装，也可通过 Nix flake 构建和运行。整体上它不调用任何模型，只做本地数据的读取、聚合与展示，费用估算依赖内置或离线缓存的定价数据。
ccusage 读取各编码 Agent CLI 存放在本地的会话/用量数据，把原始 token 记录解析后按日期、周、月或会话分组，并统计输入、输出、缓存写入与缓存读取 token 以及按模型拆分的费用。它提供 daily、weekly、monthly、session 等子命令，blocks 用于查看 Claude Code 的 5 小时计费窗口，statusline 为 Claude Code 状态栏钩子输出紧凑用量（Beta）。来源专属命令如 ccusage claude daily、ccusage codex daily、ccusage gemini daily 只统计单一来源；--all、--sections、--by-agent 用于控制统一报表的内容。输出为彩色表格（窄终端自动进入紧凑模式，--compact 可强制紧凑），--json 输出结构化数据；--breakdown 展示按模型的费用明细，--offline 使用预缓存定价，ccusage.json 可按原始模型名覆盖价格，--instances/--project 用于按 Claude Code 项目分组或过滤。
- 个人开发者想弄清自己这个月在 Claude Code 和 Codex 上各花了多少，需要按日/月查看 token 与美元成本。
- 同时使用多个编码 CLI（如 Claude Code、Gemini CLI、Copilot CLI）的工程师，希望把各来源用量汇总成一张统一报表。
- 需要把用量数据接进自有脚本或看板的团队，通过
--json导出后用程序处理。 - 关注 Claude Code 5 小时计费窗口是否会超额的订阅用户，用
ccusage blocks跟踪活跃窗口。 - 想在 Claude Code 状态栏常驻显示当前用量的用户，启用
statusline（Beta）。 - 需要按项目或实例拆分 Claude Code 开销的团队，使用
--instances --project过滤。
如何安装或部署这个 Agent？
无需安装，直接通过包运行器执行；也可用 Nix 构建或运行。
# npm
npx ccusage@latest
# Bun
bunx ccusage
# pnpm / pnpx
pnpm dlx ccusage
pnpx ccusage
# Nix
nix run github:ccusage/ccusage -- daily
nix build github:ccusage/ccusage如何使用这个 Agent？
运行后默认按天显示所有已检测来源的用量。常用调用如下：
# 基础报表
bunx ccusage daily # 全部检测来源按天
bunx ccusage weekly # 按周
bunx ccusage monthly # 按月
bunx ccusage session # 按会话
bunx ccusage blocks # Claude Code 5 小时计费窗口
bunx ccusage statusline # Claude Code 状态栏（Beta）
# 单一来源
bunx ccusage claude daily
bunx ccusage codex daily --speed fast
bunx ccusage gemini daily
bunx ccusage pi daily --pi-path /path/to/sessions
# 统一报表与筛选
bunx ccusage daily --all
bunx ccusage daily --sections daily,monthly,session --json
bunx ccusage daily --by-agent --json
bunx ccusage daily --since 2026-04-25 --until 2026-05-16
bunx ccusage daily --last 1
bunx ccusage daily --json --no-cost --timezone UTC
# 项目维度
bunx ccusage claude daily --instances --project myproject --json如需覆盖价格，可在 ccusage.json 中按模型名配置。
这个 Agent 有哪些优点和局限？
- 一个 CLI 覆盖 18 种以上编码 Agent CLI 来源，并可用
daily/weekly/monthly/session生成跨来源统一报表。 --json、--no-cost、--since/--until/--last、--timezone、--breakdown、--offline等选项覆盖结构化导出、过滤与离线使用场景。- 提供 npx、bunx、pnpm dlx、Nix 多种运行方式，且
bunx会缓存包，重复运行更快。 - 支持
ccusage.json按原始模型名覆盖定价，以及--instances/--project按 Claude Code 项目拆分用量。 - 纯本地读取数据并聚合，不调用任何模型服务，无需 API 密钥。
- 只读取本地数据，统计结果取决于各 CLI 是否已在本地留下用量记录，无法覆盖团队或云端账户的完整消费。
- 费用估算依赖定价数据，需要
--offline或定期更新定价快照才准确；新模型可能缺少价格。 statusline状态栏集成仍标注为 Beta，接口可能变化。- 仓库许可证在元数据中标记为 NOASSERTION，但 README 声明为 MIT，采用前建议自行核对 LICENSE 文件。
- 需要 Node.js/Bun 或 Nix 运行时环境，并在有网络时首次获取包与定价数据。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| ccusage 当前 | 67 · 存在缺口 | — | ★ 19k | 今天 | Rust | Codex · Claude Code |
| ccxray | 73 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 296 | 今天 | JavaScript | Claude Code · Claude API |
| Tokscale — 跨AI编码代理的令牌用量追踪器 | 52 · 缺口较多 | 命令行工具免费 | ★ 5.7k | 1 天前 | Rust | ChatGPT · Codex · Claude Code |
| Ordewell | 67 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 203 | 1 天前 | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
该工具为只读本地用量分析器，默认读取各 agent CLI 的本地数据目录，权限面较小，故 least_privilege 给 2；但 README 推荐 npx/bunx 直接执行最新版，无版本锁定或完整性校验，且运行时可能联网刷新 LiteLLM 定价，用户确认机制缺失（user_confirmation 仅 1）。数据流透明度较好：文档明确列出各数据源路径、环境变量与 --offline 语义（2）。敏感数据处理方面文档提示不要在配置中放密钥，且 --no-cost 可隐藏成本，但未说明本地会话数据是否含敏感内容（2）。依赖安全仅见 socket.dev 徽章与 pnpm only-allow，无锁文件或审计证据（1）。外部影响有限（只读+可选网络），给 2。回滚方面仅安装文档有卸载说明，无数据/配置回滚机制（1）。来源归属清晰标注 MIT 与作者（2）。
文档内部对配置优先级存在不一致：config-files.md 与 configuration.md 对环境变量与本地配置的相对优先级描述不同，故 self_consistency 扣至 2。依赖可用性有 Node/Bun 版本要求与多包管理器说明（2）。故障排查覆盖无数据、权限、网络、版本冲突等，failure_messages 给 2。
面向多 agent CLI 用户，场景覆盖日/周/月/会话/计费窗口/状态栏，audience_and_scenarios 给 3。能力边界有说明（只读本地数据、成本为估算），但未系统列出不支持项（2）。触发精度：命令与命名空间清晰，但默认聚合全部来源可能产生意外范围（2）。环境适配强：多运行时、Nix、离线、时区、自定义路径（3）。
信息架构优秀，文档分章清晰（3）。安装说明详尽含多包管理器与排错（3）。命名稳定性：命令命名空间多且含 Beta 状态栏，存在演进风险（2）。示例与 FAQ 丰富（3）。已知限制薄弱，仅零散提及 Beta 与估算成本，无集中限制章节（1）。许可证：README 与 LICENSE 为 MIT，但元数据为 NOASSERTION，存在不一致，扣至 2。版本化：有 npm 版本徽章与 monorepo 版本号，但无 CHANGELOG（1）。维护责任：有赞助与作者信息，但发布者未经验证（2）。
输出可用性强：表格、JSON、紧凑模式、时区与过滤（3）。边际价值：对多 agent 用量与成本汇总有实际价值，但成本为估算且依赖定价快照（2）。成本效益：npx 首次较慢、需网络刷新定价，但可离线与缓存（2）。
声明可追溯性弱：成本与用量为估算，未提供与官方账单的核对方法（1）。跨源佐证有限，仅徽章与外部链接（1）。事实与推断分离尚可：文档区分 display/calculate 模式与估算性质（2）。
- README 推荐 npx/bunx 直接运行最新版，无版本锁定或完整性校验，供应链风险需自行评估。
- 成本为基于 LiteLLM 定价快照的估算，可能与官方账单不符，不应作为计费依据。
- 默认聚合所有检测到的来源，可能读取超出预期的本地数据目录，建议用命名空间或路径限制范围。
- 配置优先级文档存在不一致，实际行为需以 --debug 输出为准。
- 许可证元数据为 NOASSERTION 与 README/LICENSE 的 MIT 不一致，使用前应核实。
常见问题
ccusage 会上传我的用量数据吗？
--offline 会使用预缓存定价而不联网。定价数据本身可能来自网络获取，但用量数据本身没有上传到任何服务的描述。支持哪些编码 CLI？
daily 等命令合并全部检测到的来源。费用数字准确吗？
ccusage.json 按模型名覆盖价格；若模型缺少价格或定价过期，数字会偏差，可用 --offline 配合已更新的价格快照。能接入自动化流程吗？
--json 输出结构化数据，--sections、--by-agent 可控制报表分段；但需要你自己编写调度与消费逻辑，工具本身不提供守护进程或服务端接口。