用途：为 Claude Code 会话提供接近真实的 token 用量与成本报告。它直接解析 ~/.claude/projects/{encoded-path}/ 下的 JSONL 文件，包括父会话 {session-uuid}.jsonl 与子代理侧链 {session-uuid}/subagents/{agent-id}.jsonl，并读取 sessions-index.json 获取会话摘要。资料称社区工具 ccusage 对重度用户会少算 77%–94% 的输出 token，本工具通过读取全部 JSONL 文件来修正。
主要能力：输出 Input、Output、CacheW、CacheR、Total 与 Cost 列；支持 --by day/week/month/session/model/project 聚合；支持 --since、--until、--project 过滤；支持 --json、--csv 输出，以及 --compare 与 ccusage 对比。claude_usage_report.py 可生成深色编辑风格 PDF 报告，含柱状图、模型分布与明细表，需 Playwright 与 Chromium，也可用 --html 仅输出 HTML。
用法示例：python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --since 7d；python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --by model --since 7d；python3 ~/.claude/skills/claude-usage/scripts/claude_usage_report.py --since 30d。
限制：成本基于脚本内硬编码定价表估算，Anthropic 实际账单可能因批量折扣或促销不同；预估准确率约 95%，未计入数据驻留倍率；流式分块按 message ID 去重；合成条目与计费错误条目会被过滤；需 Python 3.9+；PDF 需 Playwright 与 Chromium。定价表需在 Anthropic 调价后手动更新。