ccusage-report_skill

Overview

This skill reports Claude Code token consumption and costs using the ccusage toolchain. It maps user intents to the correct ccusage subcommand (daily, weekly, monthly), runs bunx ccusage, and formats a concise usage summary showing tokens and USD costs. It is built for quick chat responses and cron/Telegram contexts.

How this skill works

The skill inspects the user's requested period and maps it to one of three valid subcommands: daily, weekly, or monthly. It runs bunx ccusage with appropriate flags (timezone, breakdown if requested, and explicit --since/--until when needed), parses the tool output, and formats a short report showing input/output/cache/total tokens and cost. It also handles errors from bunx and empty results with clear, actionable messages.

When to use it

• When a user asks about Claude Code usage, tokens consumed, or API spending.
• When the user requests a daily, weekly, or monthly summary.
• When the user asks for per-model breakdowns (use --breakdown).
• When running scheduled reports (cron) that must output only the report.
• When the user asks for a specific range like last 7 days or a specific month.

Best practices

• Always map natural language to one of the three valid subcommands: daily, weekly, monthly — other subcommands will crash the tool.
• Add --since and --until when the user specifies exact dates or ranges (e.g., last 7 days).
• Use --breakdown only when the user requests per-model details to avoid excessive output.
• Set a timezone (-z) to keep date boundaries consistent with user expectations.
• In cron/Telegram contexts return only the formatted report (no additional commentary).

Example use cases

• "Show my Claude Code usage" → run bunx ccusage daily and return today's summary.
• "How much did I spend this week?" → run weekly and report total tokens and USD cost.
• "Monthly report with model breakdown" → run monthly with --breakdown and list per-model token and cost rows.
• "Usage for the last 7 days" → run daily with --since set to 7 days ago and summarize totals.
• Scheduled daily Telegram report → produce only the formatted code-block message for the period.