Skip to content
LLM Usage Metrics

Wrapped Recap

llm-usage wrapped condenses a full year of local usage into a single recap: totals, active days, the longest daily streak, estimated activity hours and time patterns, estimated cache savings, the top models and sources, a month-by-month intensity strip in the terminal, and a day-by-day activity heatmap in the share report.

Command structure

Section titled “Command structure”
llm-usage wrapped [options]

Examples:

Terminal window
llm-usage wrapped
llm-usage wrapped --year 2026
llm-usage wrapped --year 2026 --provider anthropic
llm-usage wrapped --year 2026 --json
llm-usage wrapped --year 2026 --share

Options

Section titled “Options”
  • --year <YYYY>: the year to recap (2020–2100; defaults to the current year in the report timezone)
  • --provider <name> / --model <name>: scope the recap the same way they scope the other reports
  • shared filters apply: --source, --machine, --timezone, source-path overrides, pricing flags, and --no-history

--year owns the date range, so --since / --until are not available, and wrapped has no --repo. wrapped supports terminal, --json, --markdown, and --share output. The markdown report carries the stat table and top lists; the monthly strip and heatmap stay in the terminal and the share report.

Terminal output

Section titled “Terminal output”
┌──────────────┐
│ Wrapped 2026 │
└──────────────┘


2026-01-01 to 2026-12-31 (UTC)


Tokens          48,200,000
Cost            $214.90
Active days     143
Longest streak  21 days
Hours           312h
Peak hour       14:00
Weekday split   84% weekday
Busiest day     2026-03-17 (612,000 tokens)
Cache savings   ~$38.20
Events          8,640
Sessions        512


Monthly activity
Jan ▂  Feb █  Mar █  Apr ▄  May ▂  Jun ▁  Jul ▁  Aug ·  Sep ▁  Oct ▂  Nov ▄  Dec █


Top models
╭───┬───────────────────┬────────────┬────────╮
│ # │ Model             │     Tokens │   Cost │
├───┼───────────────────┼────────────┼────────┤
│ 1 │ gpt-5.1           │ 21,400,000 │ $96.20 │
├───┼───────────────────┼────────────┼────────┤
│ 2 │ claude-sonnet-4-6 │ 14,800,000 │ $72.50 │
╰───┴───────────────────┴────────────┴────────╯

The report uses the shared boxed header, tables, and color policy; set NO_COLOR for plain text. The monthly strip draws each month as a sparkline block (▁ to █, the same eight levels as trends, scaled against the busiest month), and · for a month without usage. Terminal and JSON list the top five models and sources.

The time stats read as follows. Hours estimates activity from event timing: per session, inter-event gaps are summed with each gap capped at 5 minutes, so a session left open overnight contributes at most 5 idle minutes per gap. Time where sessions overlap (parallel sessions, or several sources at once) counts once, so Hours is wall-clock time and never exceeds 24h per active day. It does not measure human working time. Peak hour is the hour of day (report timezone) with the most tokens. Weekday split is the share of tokens on Monday–Friday dates. Busiest day is the single date with the most tokens. Cache savings is an estimated counterfactual: what your cache-read tokens would have cost at each model’s full input rate minus what they cost at its cache-read rate; only models with a published cache-read rate contribute, and cache-write costs are deliberately ignored (it answers “what did reads save”).

Share report

Section titled “Share report”

--share writes an interactive llm-usage-wrapped-<year>.html report to the current working directory (see Interactive report); --redact and --no-open work as on the other share reports. It opens on the year under a recap: the year’s stats, the top models and sources, and a GitHub-style daily activity heatmap: one cell per day of the year, one row per weekday from Monday, shaded by quartile of your active days so a single outlier day does not flatten the rest.

JSON shape

Section titled “JSON shape”
{
  "schemaVersion": 1,
  "report": "wrapped",
  "data": {
    "year": 2026,
    "timezone": "UTC",
    "from": "2026-01-01",
    "to": "2026-12-31",
    "totalTokens": 48200000,
    "costUsd": 214.9,
    "costIncomplete": false,
    "activeDays": 143,
    "longestStreak": 21,
    "activeMs": 1123200000,
    "peakHour": { "hour": 14, "totalTokens": 5200000 },
    "weekdayTokens": 40500000,
    "weekendTokens": 7700000,
    "busiestDay": { "date": "2026-03-17", "totalTokens": 612000, "costUsd": 2.9 },
    "estimatedCacheSavingsUsd": 38.2,
    "eventCount": 8640,
    "sessionCount": 512,
    "topModels": [{ "name": "gpt-5.1", "totalTokens": 21400000, "costUsd": 96.2 }],
    "topSources": [{ "name": "codex", "totalTokens": 26300000, "costUsd": 121.4 }],
    "monthlyIntensity": [{ "month": "2026-01", "totalTokens": 2000000, "level": 2 }],
    "dailyIntensity": [{ "date": "2026-01-01", "totalTokens": 120000, "level": 2 }]
  }
}

dailyIntensity carries one entry per day of the year (inactive days included at level 0). Active days are banded into quartile levels 1–4, which is what the share report’s heatmap renders.