claude-usage

# Claude Usage Ground-truth token usage and cost reporting for Claude Code sessions. Parses JSONL files directly—parent sessions and subagent sidechains—to produce accurate numbers. ## Why This Exists ccusage (v18+, the standard community tool with 10.6k stars) **undercounts output tokens by 77-94%** for heavy users: | Source | Output Tokens | Notes | |--------|-------------|-------| | Raw JSONL (all files) | 1,076,691 | Ground truth | | Raw JSONL (date-filtered) | 412,987 | Properly filtered | | ccusage --timezone UTC | 93,960 | 77% undercount | | ccusage default | 62,375 | 94% undercount | Three compounding bugs: 1. **Ignores subagent files** at `{session-uuid}/subagents/{agent-id}.jsonl`—132 files missed on a typical day with Agent Teams 2. **Timezone confusion** between UTC entry timestamps and local time filtering 3. **Drops entries** in parent files—even at UTC, reports only 23% of actual tokens This script reads every JSONL file to produce correct totals. --- ## Usage ```bash # 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/skil...