mcpField
C
claude-usage

claude-usage

github.com/tdiminoAgent 工作流4164 次安装1 周前更新
代码仓库

关于 claude-usage

用于统计 Claude Code Token 用量和估算费用的 Python 工具。它解析主会话及子 Agent 的 JSONL 文件，支持时间筛选与多种分组，并可生成 PDF 或 HTML 报告。

主要功能

  1. 01解析会话及子 Agent 的 JSONL 文件
  2. 02统计 Token 总量并估算费用
  3. 03按日期、会话、模型或项目分组
  4. 04支持按时区筛选日期
  5. 05生成 PDF 或 HTML 报告

适用场景

  1. 01查看 Claude Code 每日或每周用量
  2. 02比较不同模型或项目的用量
  3. 03制作可分享的用量报告

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tdimino/claude-code-minoan --skill claude-usage

安装后在 Claude Code 中输入/claude-usage确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
scripts/
claude_usage_report.py
claude_usage.py

详细介绍

Claude 使用情况

为 Claude Code 会话提供准确的 Token 用量和费用报告。直接解析 JSONL 文件——包括父会话和子 Agent 支线会话——以生成准确数据。

存在的原因

对于高用量用户，ccusage（v18+，拥有 10.6k 星的标准社区工具）会少计 77-94% 的输出 Token：

来源输出 Token说明
原始 JSONL（所有文件）1,076,691真实数据
原始 JSONL（按日期筛选）412,987正确筛选
ccusage --timezone UTC93,960少计 77%
ccusage 默认62,375少计 94%

三个叠加的错误：

  1. 忽略子 Agent 文件 {session-uuid}/subagents/{agent-id}.jsonl——在使用 Agent Teams 的典型一天中漏掉 132 个文件
  2. 时区混淆：UTC 条目时间戳与本地时间筛选不一致
  3. 漏掉父文件中的条目——即使使用 UTC，报告的 Token 也仅为实际值的 23%

此脚本会读取每个 JSONL 文件，生成正确的总计。

用法

# Today's usage (default)
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py

# Last 7 days, broken down by day
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --since 7d

# Weekly breakdown for the past month
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --by week --since 30d

# Per-model breakdown
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --by model --since 7d

# Per-session with human-readable summaries
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --by session --since 1d

# Per-project breakdown
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --by project --since 7d

# Filter to one project
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --project Thera --since 30d

# Custom date range
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --since 2026-02-01 --until 2026-02-28

# JSON output (pipe to jq)
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --since 7d --json | jq '.grand_total'

# CSV output
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --since 7d --csv

# Compare against ccusage (shows delta)
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --compare

# PDF report (dark editorial, CTO-ready)
python3 ~/.claude/skills/claude-usage/scripts/claude_usage_report.py --since 30d

# PDF with custom output path
python3 ~/.claude/skills/claude-usage/scripts/claude_usage_report.py --since 30d -o ~/Desktop/feb-usage.pdf

# HTML only (no Playwright needed)
python3 ~/.claude/skills/claude-usage/scripts/claude_usage_report.py --since 7d --html

输出列

列说明
Input提示词 Token（按输入费率计费）
Output响应 Token（费用最高的类别）
CacheW缓存写入 Token（cache_creation_input_tokens）
CacheR缓存读取 Token（费用显著低于输入 Token）
Total四种 Token 类型的总和
Cost根据硬编码价格表估算的美元金额

聚合模式（--by）

模式分组依据示例键
day（默认）本地时区的日历日期2026-02-20
weekISO 周数2026-W08
month月份2026-02
session会话 UUID（从 sessions-index.json 解析摘要）8a6c801a Working on Claudicle...
model模型名称claude-opus-4-6
project项目目录（解码为路径）~/Desktop/Programming

价格表

价格硬编码在 claude_usage.py 顶部的 PRICING 字典中。Anthropic 调整费率时请更新。键为模型名称子字符串，并按具体程度从高到低匹配。

当前默认值（每百万 Token 的美元价格，已于 2026-02-21 验证）：

模型输入输出缓存写入（1 小时）缓存读取
Opus 4.5 / 4.6$5.00$25.00$10.00$0.50
Opus 4.0 / 4.1$15.00$75.00$30.00$1.50
Sonnet 4.x$3.00$15.00$6.00$0.30
Haiku 4.5$1.00$5.00$2.00$0.10
Sonnet 3.7 / 3.5$3.00$15.00$6.00$0.30
Haiku 3.5$0.80$4.00$1.60$0.08
Opus 3$15.00$75.00$30.00$1.50
Haiku 3$0.25$1.25$0.50$0.03

缓存写入列显示 1 小时费率（基础输入价格的 2 倍）。Claude Code 仅使用 1 小时提示词缓存。如果 JSONL 的 cache_creation 子对象提供了 TTL 拆分，也支持 5 分钟费率（基础输入价格的 1.25 倍）。

时区处理

JSONL 时间戳为 UTC。脚本会先将时间戳转换为系统本地时区（或 --tz America/New_York），再应用 --since/--until 筛选条件。这可以避免午夜边界混淆，防止 ccusage 在 UTC 日期与本地日期不同时漏掉条目。

数据来源

位于 ~/.claude/projects/{encoded-path}/ 的 JSONL 文件：

  • 父会话：{session-uuid}.jsonl
  • 子 Agent 支线会话：{session-uuid}/subagents/{agent-id}.jsonl
  • 会话元数据：sessions-index.json（供 --by session 使用的摘要）

脚本逐行流式读取（O(1) 内存），可处理超过 300MB 的文件。

PDF 报告

claude_usage_report.py 可生成深色编辑风格的 PDF，采用 Crimson Pro + JetBrains Mono 字体、金色米诺斯风格点缀、条形图、带颜色编码堆叠条形图的模型分布、令牌构成明细和详细表格。专为与高管分享而设计。

需要 Playwright（uv pip install --system playwright && playwright install chromium）。使用 Chromium 实现像素级精准的 CSS 渲染，与 Aldea Slide Deck 技能使用相同的引擎。使用 --html 标志时会回退为 HTML 输出。

注意事项

  • 准确率估计：约 95%。 剩余误差来自数据驻留乘数（仅限美国推理为 1.1 倍，未跟踪）以及流式块边界处可能出现的边缘情况。
  • 按消息 ID 对流式块去重，并采用后者优先策略——output_tokens 会在各块之间单调递增，因此每个消息 ID 只有最后一个块的值才准确。不去重会导致费用被高估 2 到 5 倍。
  • 费用根据定价表估算。由于批量折扣或促销定价，Anthropic 的账单可能有所不同。
  • 默认使用 1 小时费率计算缓存写入费用（Claude Code 的缓存模式）。当 JSONL 提供 cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens 时，会相应拆分费率。
  • 自动过滤合成条目（model: "<synthetic>"）和账单错误条目（令牌计数全为零）。
  • 输出页脚会统计并报告格式错误的 JSON 行和重复的流式块。
  • 需要 Python 3.9+，以使用 zoneinfo 模块。
  • PDF 报告需要 Playwright 和 Chromium（playwright install chromium）。报告包含定价方法部分，其中提供完整的费率表、公式和置信度标记。

评论

支持 Markdown