AI Usage Report
Generates a self-contained HTML file with a token & cost overview across Claude Code, Codex, and Hermes for a freely chosen period. Layout: KPI cards · cost/token donut · three agent cards (input/output/cache/models) · breakdown table · daily line and stacked-bar charts with hover tooltips. Dark theme, print-/share-friendly, no external dependencies in the finished HTML.
The data source is ccusage (via npx), which knows all three tools natively. Charts and overview always
use the same period and the same data.
Workflow
Determine the period as
--since/--until(bothYYYY-MM-DD, inclusive). Derive it from the current date:- "for June" / "June 2026" →
--since 2026-06-01 --until 2026-06-30(if the month is still running,--until= today). - "last 7 days" →
--until= today,--since= today − 6. - "this month" / "so far this month" → first of the month until today.
- "last month" → from the first to the last day of the previous month.
- A concrete span like "May 1–15" → accordingly. On genuine ambiguity, ask briefly; otherwise default sensibly (current month up to today).
- "for June" / "June 2026" →
Generate (path relative to this skill's directory — substitute the skill's actual base directory):
node "<skill-dir>/scripts/generate.mjs" --since <YYYY-MM-DD> --until <YYYY-MM-DD> [--out <path.html>]When installed via
skillctl,<skill-dir>is~/.claude/skills/ai-usage-report; in this repo it isagent-skills/ai-usage-report. The script pulls ccusage itself (claude/codex/hermes), aggregates, and writes the HTML. The first call fetchesccusagevianpx(short delay), cached afterward.Report the result: The script prints a summary (file path, total cost, tokens, cache-read share, per-tool breakdown). Pass this on to the user concisely.
Options (scripts/generate.mjs)
--since YYYY-MM-DD·--until YYYY-MM-DD— period (required, inclusive).--out <path>— target HTML. Default: for a full monthYYYY-MM_ai-usage-report.html, otherwiseai-usage-report_<since>_<until>.html(in the current working directory).--title "..."— overrides the large heading (otherwise automatic, e.g. "June 2026" or the date span).
Notes
- Heading: If
--sincestarts on the first of the month and--untilis in the same month, the report is titled as a monthly report ("June 2026"); otherwise as a date span ("May 14 – June 24, 2026"). - Default location for monthly reports (adjust to your own setup):
~/Documents/Reports/YYYY-MM_ai-usage-report.html— for a full month set--outthere or run the script from that folder. - Cache reads dominate the token counts (very cheap) — high token peaks ≠ proportional cost.
- If a tool is missing or returns no data, it is counted as 0 (warning on stderr); the report stays valid.
- Pure logic in the script — for layout/column changes, edit
scripts/generate.mjs.