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 (both YYYY-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).
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 is
agent-skills/ai-usage-report. The script pulls ccusage itself (claude/codex/hermes), aggregates, and writes the HTML.
The first call fetches ccusage via npx (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 month YYYY-MM_ai-usage-report.html,
otherwise ai-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
--since starts on the first of the month and --until is 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 --out there 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.
1---2name: ai-usage-report3description: Generates a self-contained HTML report on token usage and cost of the AI CLI tools (Claude Code · Codex · Hermes) for any time period — KPIs, cost/token donuts, agent cards, a breakdown table, and daily trend charts (line + stacked bar). Data comes live from ccusage (local transcripts). Trigger on requests like "ai usage report for June", "token report last 7 days", "how much did I spend on AI this month", "cost overview Claude/Codex/Hermes for [period]", or German equivalents like "ai usage report für Juni" / "token-bericht letzte 7 tage".4---56# AI Usage Report78Generates a self-contained HTML file with a token & cost overview across **Claude Code, Codex, and Hermes**9for a freely chosen period. Layout: KPI cards · cost/token donut · three agent cards (input/output/cache/models) ·10breakdown table · daily line and stacked-bar charts with hover tooltips. Dark theme, print-/share-friendly,11no external dependencies in the finished HTML.1213The data source is **`ccusage`** (via `npx`), which knows all three tools natively. Charts and overview always14use **the same period and the same data**.1516## Workflow17181. **Determine the period** as `--since` / `--until` (both `YYYY-MM-DD`, inclusive). Derive it from the current date:19 - "for June" / "June 2026" → `--since 2026-06-01 --until 2026-06-30` (if the month is still running, `--until` = today).20 - "last 7 days" → `--until` = today, `--since` = today − 6.21 - "this month" / "so far this month" → first of the month until today.22 - "last month" → from the first to the last day of the previous month.23 - A concrete span like "May 1–15" → accordingly.24 On genuine ambiguity, ask briefly; otherwise default sensibly (current month up to today).25262. **Generate** (path relative to this skill's directory — substitute the skill's actual base directory):27 ```bash28 node "<skill-dir>/scripts/generate.mjs" --since <YYYY-MM-DD> --until <YYYY-MM-DD> [--out <path.html>]29 ```30 When installed via `skillctl`, `<skill-dir>` is `~/.claude/skills/ai-usage-report`; in this repo it is31 `agent-skills/ai-usage-report`. The script pulls ccusage itself (claude/codex/hermes), aggregates, and writes the HTML.32 The first call fetches `ccusage` via `npx` (short delay), cached afterward.33343. **Report the result:** The script prints a summary (file path, total cost, tokens, cache-read share, per-tool35 breakdown). Pass this on to the user concisely.3637## Options (scripts/generate.mjs)3839- `--since YYYY-MM-DD` · `--until YYYY-MM-DD` — period (required, inclusive).40- `--out <path>` — target HTML. Default: for a full month `YYYY-MM_ai-usage-report.html`,41 otherwise `ai-usage-report_<since>_<until>.html` (in the current working directory).42- `--title "..."` — overrides the large heading (otherwise automatic, e.g. "June 2026" or the date span).4344## Notes4546- **Heading:** If `--since` starts on the first of the month and `--until` is in the same month, the report is47 titled as a monthly report ("June 2026"); otherwise as a date span ("May 14 – June 24, 2026").48- **Default location** for monthly reports (adjust to your own setup): `~/Documents/Reports/YYYY-MM_ai-usage-report.html`49 — for a full month set `--out` there or run the script from that folder.50- **Cache reads** dominate the token counts (very cheap) — high token peaks ≠ proportional cost.51- If a tool is missing or returns no data, it is counted as 0 (warning on stderr); the report stays valid.52- Pure logic in the script — for layout/column changes, edit `scripts/generate.mjs`.
mdeuerlein