Version 0.8.0

~/.claude · ~/.codex · ~/.gemini · 13 more

Your coding agents leave receipts.

Sixteen coding tools already write session logs to your disk. llm-usage reads them in place, prices what it can — and marks what it can’t — then turns the result into reports you can inspect, compare, and export. Nothing leaves your machine.

Get your first reportView source

~ llm-usagelocal

Example: llm-usage compare --source codex,claude reads 49 session files with 2,080 events and compares 2026-01 against 2025-12 — 117.8 million total tokens versus 84.9 million (up 38.7%), $662.35 versus $476.41 (up 39.0%), with per-source cost deltas for codex and claude.

16 source adapters4 output familiesoffline pricing snapshot0 session uploads
Reads local history from
  • claude
  • codex
  • pi
  • openclaw
  • copilot
  • qwen
  • kimi
  • gemini
  • droid
  • amp
  • cline
  • roocode
  • kilocode
  • opencode
  • goose
  • antigravity

# 01 · reports

Ask the question first. There’s a table for it.

Start with a calendar rollup, then move to sessions, repositories, or candidate pricing when you need a narrower answer.

01Usage

How much did I use?

Roll up tokens and estimated cost by day, week, or month. Compare two windows or chart a daily trend.

Try it llm-usage daily llm-usage weekly llm-usage monthly llm-usage compare llm-usage trends
02Sessions

Which work used the most?

Rank conversations by cost, inspect a matching session ID, or group the same history by repository.

Try it llm-usage session llm-usage session --by-repo
03Efficiency

How does usage line up with Git?

Join repo-attributed usage with your commits and line changes. Use the ratios as review signals, with the raw denominators beside them.

Try it llm-usage efficiency monthly
04Optimize

What would another model cost?

Replay the token mix you observed against candidate pricing without changing your source data.

Try it llm-usage optimize monthly
05Health

Is my local data healthy?

Probe every discovery path, inspect the event ledger, and preview retained-history cleanup before deleting anything.

Try it llm-usage doctor llm-usage prune llm-usage config show
06Wrapped

What did the year look like?

Summarize active days, streaks, models, sources, tokens, and estimated cost in one terminal recap or SVG.

Try it llm-usage wrapped
07Export

Can I take the data with me?

Stream every normalized event as JSONL or CSV for jq, DuckDB, or warehouse workflows — with published JSON Schemas to validate any report output against.

Try it llm-usage events --format csv llm-usage schema usage
Browse every command and option

# 02 · pipeline

Four stages. One pipe.

The useful engineering sits between the files and the table. Every report runs the same pipeline, so sixteen different log formats behave like one dataset.

  1. 01discover

    Find each tool’s local data in its default location, or the paths in your TOML config.

  2. 02normalize

    Convert source-specific records into one deterministic usage-event shape.

  3. 03price

    Keep explicit cost when a tool recorded it; estimate the rest from cached LiteLLM data.

  4. 04report

    Aggregate once, then render terminal tables, JSON, Markdown, or SVG.

Persistent ledger

Unchanged files do not need another parse.

A local SQLite event store keeps normalized events and parse diagnostics. It also powers optional history for session files that have left the disk.

How the event store works
Honest pricing

Unknown cost stays unknown.

Reports mark partial estimates with ~ and unresolved rows with-. The cost engine does not invent a rate for a token bucket it cannot price.

Read the pricing rules

# 03 · sources

Sixteen adapters. One event shape.

Each adapter discovers its tool’s local data — JSONL, JSON, or SQLite — and converts it into the same usage event. Filters, pricing, aggregation, and exports work identically after that boundary.

See discovery paths and overrides
  • claudejsonl
  • codexjsonl
  • pijsonl
  • openclawjsonl
  • copilotjsonl
  • qwenjsonl
  • kimijsonl
  • geminijson
  • droidjson
  • ampjson
  • clinejson
  • roocodejson
  • kilocodejson
  • opencodesqlite
  • goosesqlite
  • antigravitysqlite

# 04 · wrapped

A year of sessions fits in one artifact.

llm-usage wrapped recaps active days, streaks, models, sources, tokens, and estimated cost — in the terminal, or as an SVG you can share.

llm-usage wrapped --shareillustrative activity — your recap uses your own sessions

# 05 · benchmarks

Performance numbers you can audit.

The benchmark records eight-run medians on stable snapshots of real local corpora and publishes the machine, commands, application state, and dataset size. The current direct comparison favors ccusage; a separate launcher test explains why npx can reverse the result you see at the shell.

Read the benchmark and reproduce it
Largest measured corpus
1.77 GiB
1,168 codex session files
Warm Codex median
0.766 s
built llm-usage, direct process
Runs per cell
8
rotated order; summary statistics published

# 06 · start

The sessions are already on your disk. Ask them something.

Open the setup guideView on npm