# AI Usage Report

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

- Skill: `mdeuerlein/ai-usage-report` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mdeuerlein/ai-usage-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mdeuerlein/ai-usage-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: mdeuerlein (https://skillmd.com/u/mdeuerlein)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mdeuerlein/ai-usage-report

---


# 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

1. **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).

2. **Generate** (path relative to this skill's directory — substitute the skill's actual base directory):
   ```bash
   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.

3. **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`.