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, hands-on 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 SVG.

Command structure

Section titled “Command structure”
Terminal window
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, --timezone, source-path overrides, pricing flags, and --history

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

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 renders each month’s relative intensity with block glyphs (·▁▂▄█, scaled against the busiest month). Terminal and JSON list the top five models and sources.

The time stats read as follows. Hours is gap-capped hands-on time: 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. 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 SVG

Section titled “Share SVG”

--share writes an offline SVG named llm-usage-wrapped-<year>.svg to the current working directory. It shows five stat tiles (tokens, cost with cache savings, hours, active days, streak), the top three models and sources, and a GitHub-style daily activity heatmap: one cell per day of the year, shaded by quartile of your active days so a single outlier day does not flatten the rest. PNG rendering and embedded logo/font assets are intentionally out of scope.

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 SVG heatmap renders.