Llm Usage Metrics

llm-usage-metrics

  Usage reports for AI coding tools, across all your machines.

  Documentation ·
  Getting started ·
  CLI reference ·
  Contributing

llm-usage-metrics reads local session data from 17 AI coding tools, on this machine and on others you reach over ssh, and converts it into one normalized usage history. Use it to review tokens and estimated cost by day, hour, project or session, compare periods, check usage against 5-hour plan windows and subscription prices, correlate usage with local Git activity, explore it all in an interactive HTML report, or export the events.

The CLI parses session content on your machine. It discovers standard source locations and includes a bundled pricing snapshot, so the first report can run without configuration or network access.

See Privacy for what it reads, stores, and sends over the network.

Quick start

Requires Node.js 22.16+ or 24+ (Node 23 lacks the SQLite busy timeout the ledger uses), or Bun 1.4+.

With no command, llm-usage prints cost and tokens for today, the last 7 days, and month to date, a month-end projection (checked against monthlyBudgetUsd when you set one), what prompt caching saved you this month, a note when a day of the last 7 cost at least $1 and at least 3 times your median active day, then your current and longest streak, best day, and a year-long activity heatmap. llm-usage daily breaks the last 7 days down by day and source, and llm-usage weekly covers the last 8 weeks; add --since YYYY-MM-DD or --all for older usage.

If the report is empty, check source discovery. doctor marks each source found, not installed, or unparseable and lists the paths it searched (--verbose adds the paths of sources that are not installed):

Reports

Common examples:

Supported sources

In the Real logs column,…