claude-usage
Report ground-truth Claude token consumption and estimated cost by parsing JSONL session files directly. Use when checking API spend, auditing token usage by project/session/model, generating daily/weekly/monthly cost reports, or diagnosing ccusage undercounting. Includes subagent files that ccusage ignores.
npx skills add majiayu000/claude-skill-registry --skill claude-usage --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# 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 # Weekl
- Why This Exists
- Usage
- Output Columns
- Aggregation Modes (--by)
- Pricing Table
- Timezone Handling
- Data Sources
- PDF Reports
- Caveats
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
What does the claude-usage skill do?
Report ground-truth Claude token consumption and estimated cost by parsing JSONL session files directly. Use when checking API spend, auditing token usage by project/session/model, generating daily/weekly/monthly cost reports, or diagnosing ccusage undercounting. Includes subagent files that ccusage ignores.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill claude-usage --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.