ccusage-report

# 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 ``` 📊 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)` |