Ccusage Report

Report Claude Code token consumption and costs using ccusage. Use when the user asks about their Claude Code usage, token consumption, API costs, spending, or wants a daily/weekly/monthly usage summary.

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

json

{ "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

text

📊 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 ccusage fails → 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)