# LLM Usage Metrics

> llm-usage-metrics is a local CLI that reads session logs from 17 AI coding tools and reports tokens and estimated cost by day, hour, project, session, 5-hour block and subscription plan, with trends, comparisons, tool-call counts, prompt sizes and a self-contained interactive HTML report. Install with `npm i -g llm-usage-metrics` and run `llm-usage`. Its parsers are also a Node.js library, `@ayagmar/agent-sessions`, that reads the same logs as events.

All docs pages in one file: https://ayagmar.github.io/llm-usage-metrics/llms-full.txt

## Start here

- [Documentation](https://ayagmar.github.io/llm-usage-metrics/docs/): Understand local LLM usage, pricing, sessions, and reports.
- [Getting Started](https://ayagmar.github.io/llm-usage-metrics/getting-started/): Install the CLI, run a local report, and learn where to go next.
- [Choose a Report](https://ayagmar.github.io/llm-usage-metrics/reports/): Find the command that answers your usage question, with defaults and examples.
- [Data Sources](https://ayagmar.github.io/llm-usage-metrics/sources/): Default locations, formats, and path overrides for every supported source adapter.
- [Configuration](https://ayagmar.github.io/llm-usage-metrics/configuration/): Config file, CLI precedence, source path overrides, and runtime environment overrides.
- [Use with coding agents](https://ayagmar.github.io/llm-usage-metrics/agents/): Install the llm-usage-metrics skill so Claude Code, Codex, and other agents answer spend and usage questions with the CLI.

## Reports

- [Usage Totals](https://ayagmar.github.io/llm-usage-metrics/usage/): Review hourly, daily, weekly, and monthly tokens and cost across local coding tools.
- [Projects](https://ayagmar.github.io/llm-usage-metrics/projects/): Cost, tokens, and activity per recorded working directory.
- [Compare Periods](https://ayagmar.github.io/llm-usage-metrics/compare/): Compare tokens, cost, events, and active days between two date windows.
- [Session Report](https://ayagmar.github.io/llm-usage-metrics/session/): Per-conversation usage, cost, and repository attribution across sources.
- [Tool calls](https://ayagmar.github.io/llm-usage-metrics/tools/): Tool calls per tool from Claude Code, Codex and pi logs, with errors, error rate, and sessions.
- [Context Pressure](https://ayagmar.github.io/llm-usage-metrics/context/): Peak prompt sizes per model or session, long-context requests and their tier cost, and requests near the context limit.
- [Trends](https://ayagmar.github.io/llm-usage-metrics/trends/): Chart daily cost or token usage in the terminal, JSON, or an interactive share report.
- [5-hour blocks](https://ayagmar.github.io/llm-usage-metrics/blocks/): Estimated 5-hour usage blocks per source, with the active block.
- [Plan value](https://ayagmar.github.io/llm-usage-metrics/value/): Compare API-priced cost with subscription plan prices.
- [Efficiency](https://ayagmar.github.io/llm-usage-metrics/efficiency/): Join repo-attributed usage with local Git activity and interpret the ratios carefully.
- [Optimize](https://ayagmar.github.io/llm-usage-metrics/optimize/): Counterfactual pricing report for candidate models.
- [Wrapped Recap](https://ayagmar.github.io/llm-usage-metrics/wrapped/): A yearly usage recap in the terminal and as an interactive share report.
- [Interactive report](https://ayagmar.github.io/llm-usage-metrics/share/): Self-contained HTML reports you can filter, explore, and share.
- [Status line](https://ayagmar.github.io/llm-usage-metrics/statusline/): Show today's cost, your streak, and month to date in Claude Code, tmux, or starship, plus the session's cost and context use in Claude Code.
- [Events Export](https://ayagmar.github.io/llm-usage-metrics/events/): Stream normalized usage events as JSONL or CSV for jq, DuckDB, or warehouse workflows, or export them as OpenTelemetry traces and metrics.
- [OpenTelemetry Export](https://ayagmar.github.io/llm-usage-metrics/otel/): Export sessions as OTLP/JSON traces and daily token and cost metrics that follow the OpenTelemetry GenAI conventions, and replay them into any OTLP backend.
- [Output Formats](https://ayagmar.github.io/llm-usage-metrics/output-formats/): Choose terminal, JSON, Markdown, or an interactive share report.

## Operate

- [Pricing](https://ayagmar.github.io/llm-usage-metrics/pricing/): How pricing is loaded and how row costs are computed.
- [Caching](https://ayagmar.github.io/llm-usage-metrics/caching/): Why caching exists, how each cache works, and how to tune it.
- [Multiple machines](https://ayagmar.github.io/llm-usage-metrics/machines/): Combine usage from your laptop, desktop, and servers into one report over ssh.
- [Doctor](https://ayagmar.github.io/llm-usage-metrics/doctor/): Check where each source is searched, whether usage is readable, and event-store health.
- [Troubleshooting](https://ayagmar.github.io/llm-usage-metrics/troubleshooting/): Diagnose empty reports, source paths, missing prices, and local ledger problems.
- [Privacy](https://ayagmar.github.io/llm-usage-metrics/privacy/): What llm-usage-metrics reads, what it stores and where, and every network request it makes.
- [Security](https://ayagmar.github.io/llm-usage-metrics/security/): Security scans, dependency update flow, SHA pinning, and contributor security steps for this repo.

## Library

- [Library overview](https://ayagmar.github.io/llm-usage-metrics/library/): Read local AI coding agent sessions from Node.js with @ayagmar/agent-sessions.
- [Reading and composing](https://ayagmar.github.io/llm-usage-metrics/library/guide/): Read, collect, and dedupe events from agent logs with the library.
- [Versioning and cursors](https://ayagmar.github.io/llm-usage-metrics/library/contracts/): Stability, versioning, and incremental cursor contracts of the library.

## Source details

- [Data Sources](https://ayagmar.github.io/llm-usage-metrics/sources/): Default locations, formats, and path overrides for every supported source adapter.
- [Amp Source](https://ayagmar.github.io/llm-usage-metrics/sources/amp/): Discovery paths, overrides, and usage parsing for Amp.
- [Antigravity Source](https://ayagmar.github.io/llm-usage-metrics/sources/antigravity/): Discovery paths, overrides, and usage parsing for Antigravity.
- [Claude Code Source](https://ayagmar.github.io/llm-usage-metrics/sources/claude/): Discovery paths, overrides, and usage parsing for Claude Code.
- [Cline Source](https://ayagmar.github.io/llm-usage-metrics/sources/cline/): Discovery paths, overrides, and usage parsing for Cline.
- [Codex Source](https://ayagmar.github.io/llm-usage-metrics/sources/codex/): Discovery paths, overrides, and usage parsing for Codex.
- [GitHub Copilot CLI Source](https://ayagmar.github.io/llm-usage-metrics/sources/copilot/): Discovery paths, overrides, and usage parsing for GitHub Copilot CLI.
- [Droid CLI Source](https://ayagmar.github.io/llm-usage-metrics/sources/droid/): Discovery paths, overrides, and usage parsing for Droid CLI.
- [DeepSeek Harness Source](https://ayagmar.github.io/llm-usage-metrics/sources/dsh/): Discovery paths, overrides, and usage parsing for DeepSeek Harness.
- [Gemini CLI Source](https://ayagmar.github.io/llm-usage-metrics/sources/gemini/): Discovery paths, overrides, and usage parsing for Gemini CLI.
- [Goose Source](https://ayagmar.github.io/llm-usage-metrics/sources/goose/): Discovery paths, overrides, and usage parsing for Goose.
- [KiloCode Source](https://ayagmar.github.io/llm-usage-metrics/sources/kilocode/): Discovery paths, overrides, and usage parsing for KiloCode.
- [Kimi Source](https://ayagmar.github.io/llm-usage-metrics/sources/kimi/): Discovery paths, overrides, and usage parsing for Kimi.
- [OpenClaw Source](https://ayagmar.github.io/llm-usage-metrics/sources/openclaw/): Discovery paths, overrides, and usage parsing for OpenClaw.
- [OpenCode Source](https://ayagmar.github.io/llm-usage-metrics/sources/opencode/): Discovery paths, overrides, and usage parsing for OpenCode.
- [Pi Source](https://ayagmar.github.io/llm-usage-metrics/sources/pi/): Discovery paths, overrides, and usage parsing for Pi.
- [Qwen CLI Source](https://ayagmar.github.io/llm-usage-metrics/sources/qwen/): Discovery paths, overrides, and usage parsing for Qwen CLI.
- [RooCode Source](https://ayagmar.github.io/llm-usage-metrics/sources/roocode/): Discovery paths, overrides, and usage parsing for RooCode.

## Reference

- [CLI Reference](https://ayagmar.github.io/llm-usage-metrics/cli-reference/): Command-line options and usage for llm-usage-metrics.
- [Benchmarks](https://ayagmar.github.io/llm-usage-metrics/benchmarks/): Direct-process and launcher-inclusive runtimes on stable snapshots of real local data.

## Upgrading

- [Upgrading](https://ayagmar.github.io/llm-usage-metrics/upgrading/): Breaking changes by version and how to update scripts and integrations.
- [Upgrading to 0.8](https://ayagmar.github.io/llm-usage-metrics/upgrading/0-8/): What changed in the 0.8.0 JSON output and how to update scripts.

## Architecture

- [Architecture](https://ayagmar.github.io/llm-usage-metrics/architecture/): High-level runtime architecture and data flow.
- [Event Store](https://ayagmar.github.io/llm-usage-metrics/architecture/event-store/): Design of the SQLite usage-event ledger: ingest, fingerprints, history, and prune.
- [Parse Pipeline](https://ayagmar.github.io/llm-usage-metrics/architecture/parse-pipeline/): How source files are discovered, filtered, parsed, and parallelized.
- [Pricing Pipeline](https://ayagmar.github.io/llm-usage-metrics/architecture/pricing-pipeline/): How LiteLLM pricing is fetched, cached, matched to local model names, and turned into costs.
- [Event model](https://ayagmar.github.io/llm-usage-metrics/architecture/event-model/): The normalized event union: usage, message, tool call, and session metadata.
- [Dedup and cursors](https://ayagmar.github.io/llm-usage-metrics/architecture/dedup-and-cursors/): How duplicate events are removed and how incremental reads resume.
- [Machine merge](https://ayagmar.github.io/llm-usage-metrics/architecture/machine-merge/): How usage from other machines is fetched and merged.
- [Share report](https://ayagmar.github.io/llm-usage-metrics/architecture/share-report/): How the interactive HTML report is built from report data.
- [Config & Logging](https://ayagmar.github.io/llm-usage-metrics/architecture/config-and-logging/): How the TOML config resolves against flags and env vars, and how stderr logging is leveled.