Claude Code Usage Report
Uses bunx ccusage to report token consumption and costs from Claude Code sessions.
IMPORTANT: The ONLY valid subcommands are daily, weekly, monthly. Do NOT use today, this_week, this_month, or any other subcommand — they will crash.
Workflow
1. Determine the subcommand
Map the user's intent to one of the three valid subcommands:
| User intent | Subcommand | Extra flags |
|---|---|---|
| "today" / "how much today" / default | daily | --since $(date +%Y%m%d) --until $(date +%Y%m%d) |
| "this week" / "weekly" | weekly | (none) |
| "this month" / "monthly" | monthly | (none) |
| "last 7 days" | daily | --since $(date -d '7 days ago' +%Y%m%d) |
| "in February" / specific month | daily | --since 20260201 --until 20260228 |
2. Run ccusage
{ "tool": "exec", "command": "bunx ccusage daily --no-color -z Europe/Paris -o desc --since $(date +%Y%m%d) --until $(date +%Y%m%d)" }
Replace daily with weekly or monthly as needed. Add --breakdown if the user asks for per-model details.
3. Format the output
📊 Claude Code Usage — <period>
Date/Period : <value>
Models : <comma-separated list>
Input : <n> tokens
Output : <n> tokens
Cache read : <n> tokens
Total : <n> tokens
Cost : $<amount> USD
For multi-row output (e.g. last 7 days), summarize totals and list each row briefly.
4. Deliver
- Chat: Send the formatted message directly
- Telegram (cron context): Reply with ONLY the formatted message in a code block — no extra commentary
5. Error handling
- If
bunx ccusagefails → check if bun/bunx is installed, report the error - If no data for the requested period → inform the user clearly ("No usage data found for this period")
- If the output is empty → suggest checking a broader date range
Examples
| User says | Period | Flags |
|---|---|---|
| "Show my claude code usage" | daily | (none) |
| "How much did I spend this week?" | weekly | (none) |
| "Monthly report with model breakdown" | monthly | --breakdown |
| "Usage for the last 7 days" | daily | --since $(date -d '7 days ago' +%Y%m%d) |