llm-usage-metrics
v0.12.1 / open source

Follow the work.
Count the tokens.

One CLI for the session logs of 17 AI coding agents. See tokens and estimated cost by day, project, and session, across every machine you work on, and open any report as an interactive page.

Get your first report Try the demo report
npm install -g llm-usage-metrics

Node.js 22.16+ or 24+, or Bun macOS, Linux, Windows MIT

Terminal output of llm-usage summary: cost, tokens, and top source for today, the last 7 days, and month to date, a month-end projection and caching savings, then streaks and a year-long activity heatmap.
llm-usage on demo data

17 agents.
One reporting language.

Each tool’s logs are read in place and turned into the same events, so every report covers all of them.

Check paths & setup →

See which project the tokens went to.

Every session records the folder it ran in. llm-usage projects ranks those projects by cost, with their models, share of the cost, events, and active days.

  • --by-reposplits hourly, daily, weekly, monthly, compare, session, and trends by project
  • --repo atlas-apikeeps one project in most reports, by name or by path
  • llm-usage valueshows each month’s projects next to your subscription’s price
How projects are named →
Terminal output of llm-usage projects: four projects ranked by cost, each with its models, cost, share of the cost, tokens, events, and active days, and a TOTAL row.

Open any report as an interactive page.

Add --share to summary, daily, weekly, monthly, compare, trends, wrapped, efficiency, or optimize. The CLI writes one HTML file you can filter by source, model, and project, regroup by hour, day, week, or month, and export chart by chart. The file loads nothing from the network, and --redact replaces project and machine names before you send it on.

What the page offers →
llm-usage daily --last 90 --share on generated demo data: four sources, four projects, 90 days.Open it full page

Your laptop, your desktop, your dev box. One report.

Add a machine you can reach over ssh and its usage joins every report. Each machine parses its own logs; a session that reached two of them through a synced folder counts once.

Usage also outlives the logs. Tools delete old transcripts, but the local ledger keeps what they counted, so last quarter still adds up.

Set up machines →
~/usageIllustrative data

llm-usage machine add laptop

llm-usage monthly --by-machine

SourceTokensCost (USD)
claude (local)18,240,000$96.10
claude (laptop)9,880,000$51.37
codex (devbox)6,410,000$14.82
TOTAL34,530,000$162.29

Start with what you want to know.

All reports →
Summary

How am I doing this month?

Today, the last 7 days, and the month at a glance, with your streak and a month-end projection.

llm-usage
Usage

Where did the tokens go?

Hourly, daily, weekly, and monthly totals by source, with model breakdowns and estimated cost.

llm-usage daily
Projects

Which project costs the most?

Every project in your history, costliest first, with its models and active days.

llm-usage projects
Sessions

Which conversations used the most?

Rank sessions by cost, or group them into one row per project.

llm-usage session --top 10
Compare

What changed this month?

Two periods side by side: tokens, cost, events, and active days, with the deltas.

llm-usage compare
Trends

Is usage climbing?

A daily series over a chosen window, combined, by source, or by project.

llm-usage trends --metric tokens --last 14
5-hour blocks

How much of this window is left?

Estimated 5-hour windows per source, with the active block’s time left and burn rate.

llm-usage blocks
Plan value

Is the subscription worth it?

Each month priced at API rates next to a plan’s monthly price, split by project.

llm-usage value
Status line

What is this session costing?

Today, your streak, and the month in Claude Code, tmux, or starship, plus the session cost in Claude Code.

llm-usage statusline

Does usage line up with your commits? Check efficiency. Want a year in review? Try Wrapped. Need individual events? Export JSONL or CSV.

A parsing library under a reporting CLI.

The 17 source adapters live in @ayagmar/agent-sessions, a package with no runtime dependencies that finds the logs, reads them, and yields one event shape. The CLI adds the event store, pricing, other machines, and the reports.

Read the architecture →Use the library →
Package layers: the CLI on top of the core packageTwo layers. The llm-usage-metrics CLI on top owns commands and the report runtime (src/cli), config and env vars (src/config), the SQLite event store (src/persistence), other machines over ssh (src/machines), pricing (src/pricing), the per-report aggregation directories, terminal, JSON and Markdown rendering (src/render) and the interactive HTML report (src/share-report). It imports the core package @ayagmar/agent-sessions, which the CLI build bundles. The core package owns the 17 source adapters (sources), the adapter registry and readSources (registry), reading, collecting and cursors (stream), the dedup stages (dedup), the event types and constructors (domain) and OpenTelemetry GenAI attributes (otel). It has no runtime dependencies.llm-usage-metricsCLI: reads, stores, prices, reportssrc/clicommands, runtimesrc/configconfig.toml, env varssrc/persistenceSQLite event storesrc/machinesother machines (ssh)src/pricingLiteLLM rates, costssrc/aggregate, …per-report totalssrc/rendertext, JSON, Markdownsrc/share-reportinteractive HTMLimports; bundled intothe CLI build@ayagmar/agent-sessionscore: no runtime dependenciessources/17 source adaptersregistry/adapters, readSourcesstream/read, collect, cursorsdedup/hash, repeats, copiesdomain/event typesotel/GenAI attributes
Event flow of a report runA report run passes through eleven stages in order: discover each source's files; look each file up in the event store, where an unchanged fingerprint is a hit that skips reading; read the misses; store their fresh events; drop events repeated across one source's files; merge history from departed files and events from other machines; drop events copied between sessions; filter by date, provider, model and repo; price each event; aggregate per report; render as terminal, JSON, Markdown or HTML output. Discover, read and both dedupe stages come from the @ayagmar/agent-sessions core package; the other stages live in the CLI.core packageCLI01Discoveradapter.discoverFiles() per source02Look upevent store: same fingerprint is a hit03ReadcollectFile on misses, worker threads04Storereplace the file’s stored events05Dedupe repeatsevents repeated across files (pi)06Mergehistory replay, other machines07Dedupe copiescopied sessions (claude)08Filterdates, provider, model, repo09PriceLiteLLM rates, cost per event10Aggregaterows and totals per report11Renderterminal, JSON, Markdown, HTMLmisshit

Useful numbers.
Visible limits.

Usage reports help you understand your tools. Source logs, pricing coverage, and attribution determine what each number can tell you.

How pricing works →
Your sessions stay on your machines
Parsing and reporting happen on your machines, and other machines are reached only over your own ssh. Online runs fetch pricing and check npm for updates; neither request includes your usage. Read the privacy page.
Cost coverage is explicit
Source-recorded cost is kept. Other events use available model pricing. A tilde marks partial cost; a dash means unresolved cost. Estimates may differ from your bill.
Keep the data useful outside the terminal
Export versioned JSON, Markdown, normalized events, or an interactive HTML report. Diagnostics stay separate from report data. Choose an output format.

Your first report is one command away.

Try it without installing. Standard source locations are discovered automatically.

Open the setup guide →
Try it now
npx --yes llm-usage-metrics@latest

Already installed, but seeing an empty report?

llm-usage doctorFind the cause →