llm-usage-metrics 0.3.1 → 0.3.3

package/README.md

@@ -1,341 +1,279 @@
-# llm-usage-metrics
-
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ayagmar/llm-usage-metrics)
-[![CI](https://github.com/ayagmar/llm-usage-metrics/actions/workflows/ci.yml/badge.svg)](https://github.com/ayagmar/llm-usage-metrics/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/codecov/c/github/ayagmar/llm-usage-metrics)](https://codecov.io/gh/ayagmar/llm-usage-metrics)
-[![npm version](https://img.shields.io/npm/v/llm-usage-metrics.svg)](https://www.npmjs.com/package/llm-usage-metrics)
-[![npm total downloads](https://img.shields.io/npm/dt/llm-usage-metrics.svg)](https://www.npmjs.com/package/llm-usage-metrics)
-[![install size](https://packagephobia.com/badge?p=llm-usage-metrics)](https://packagephobia.com/result?p=llm-usage-metrics)
+<div align="center">
 
-CLI to aggregate local LLM usage from:
+<img src="https://ayagmar.github.io/llm-usage-metrics/favicon.svg" width="64" height="64" alt="llm-usage-metrics logo">
 
-- `~/.pi/agent/sessions/**/*.jsonl`
-- `~/.codex/sessions/**/*.jsonl`
-- OpenCode SQLite DB (auto-discovered or provided via `--opencode-db`)
-
-Reports are available for daily, weekly (Monday-start), and monthly periods.
-
-**Documentation: [ayagmar.github.io/llm-usage-metrics](https://ayagmar.github.io/llm-usage-metrics/)**
+# llm-usage-metrics
 
-Built-in adapters currently support 3 sources: `.pi`, `.codex`, and OpenCode SQLite. The codebase is structured to add more sources (for example Claude/Gemini exports) through the `SourceAdapter` pattern. See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+**Track and analyze your local LLM usage across coding agents**
 
-## Install
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ayagmar/llm-usage-metrics)
+[![npm version](https://img.shields.io/npm/v/llm-usage-metrics.svg?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/llm-usage-metrics)
+[![npm downloads](https://img.shields.io/npm/dt/llm-usage-metrics.svg?style=flat-square&color=10b981)](https://www.npmjs.com/package/llm-usage-metrics)
+[![CI](https://img.shields.io/github/actions/workflow/status/ayagmar/llm-usage-metrics/ci.yml?style=flat-square&label=CI)](https://github.com/ayagmar/llm-usage-metrics/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/ayagmar/llm-usage-metrics?style=flat-square)](https://codecov.io/gh/ayagmar/llm-usage-metrics)
 
-```bash
-npm install -g llm-usage-metrics
-```
+[📖 Documentation](https://ayagmar.github.io/llm-usage-metrics/) ·
+[⚡ Quick Start](#quick-start) ·
+[📊 Examples](#usage) ·
+[🤝 Contributing](./CONTRIBUTING.md)
 
-Or run without global install:
+</div>
 
-```bash
-npx --yes llm-usage-metrics daily
-```
+---
 
-(`npx llm-usage daily` works when the project is already installed locally.)
+Aggregate token usage and costs from your local coding agent sessions. Supports **pi**, **codex**, and **OpenCode** with zero configuration required.
 
-Runtime notes:
+## ✨ Features
 
-- OpenCode parsing requires Node.js 24+ (`node:sqlite`).
-- pnpm is the supported dependency/script workflow for this repository.
-- Example local execution against built dist: `node dist/index.js daily --source opencode --opencode-db /path/to/opencode.db`
+- **Zero-Config Discovery** — Automatically finds `.pi`, `.codex`, and OpenCode session data
+- **LiteLLM Pricing** — Real-time pricing sync with offline caching support
+- **Flexible Reports** — Daily, weekly, and monthly aggregations
+- **Efficiency Reports** — Correlate cost/tokens with repository commit outcomes
+- **Multiple Outputs** — Terminal tables, JSON, or Markdown
+- **Smart Filtering** — By source, provider, model, and date ranges
 
-## Update checks
+## 🚀 Quick Start
 
-When installed globally, the CLI performs a lightweight npm update check on startup.
-
-Behavior:
-
-- uses a local cache (`<platform-cache-root>/llm-usage-metrics/update-check.json`; defaults to `~/.cache/llm-usage-metrics/update-check.json` on Linux when `XDG_CACHE_HOME` is unset) with a 1-hour default TTL
-- optional session-scoped cache mode via `LLM_USAGE_UPDATE_CACHE_SCOPE=session`
-- skips checks for `--help` / `--version` invocations
-- skips checks when run through `npx`
-- prompts for install + restart only in interactive TTY sessions
-- prints a one-line notice in non-interactive sessions
+```bash
+# Install globally
+npm install -g llm-usage-metrics
 
-To force-skip startup update checks:
+# Or run without installing
+npx llm-usage-metrics daily
 
-```bash
-LLM_USAGE_SKIP_UPDATE_CHECK=1 llm-usage daily
+# Generate your first report
+llm-usage daily
 ```
 
-### Runtime environment overrides
+<div align="center">
 
-You can tune runtime behavior with environment variables:
+![Terminal output showing token usage and cost breakdown](https://ayagmar.github.io/llm-usage-metrics/screenshot.png)
 
-- `LLM_USAGE_SKIP_UPDATE_CHECK`: skip startup update check when set to `1`
-- `LLM_USAGE_UPDATE_CACHE_SCOPE`: cache scope for update checks (`global` default, `session` to scope by terminal shell session)
-- `LLM_USAGE_UPDATE_CACHE_SESSION_KEY`: optional custom session key when `LLM_USAGE_UPDATE_CACHE_SCOPE=session` (defaults to parent shell PID)
-- `LLM_USAGE_UPDATE_CACHE_TTL_MS`: update-check cache TTL in milliseconds (clamped: `0..2592000000`; use `0` to check on every CLI run)
-- `LLM_USAGE_UPDATE_FETCH_TIMEOUT_MS`: update-check network timeout in milliseconds (clamped: `200..30000`)
-- `LLM_USAGE_PRICING_CACHE_TTL_MS`: pricing cache TTL in milliseconds (clamped: `60000..2592000000`)
-- `LLM_USAGE_PRICING_FETCH_TIMEOUT_MS`: pricing fetch timeout in milliseconds (clamped: `200..30000`)
-- `LLM_USAGE_PARSE_MAX_PARALLEL`: max concurrent file parses per source adapter (clamped: `1..64`)
-- `LLM_USAGE_PARSE_CACHE_ENABLED`: enable file parse cache (`1` by default; accepts `1/0`, `true/false`, `yes/no`)
-- `LLM_USAGE_PARSE_CACHE_TTL_MS`: file parse cache TTL in milliseconds (clamped: `3600000..2592000000`)
-- `LLM_USAGE_PARSE_CACHE_MAX_ENTRIES`: max cached file parse entries (clamped: `100..20000`)
-- `LLM_USAGE_PARSE_CACHE_MAX_BYTES`: max parse-cache file size in bytes (clamped: `1048576..536870912`)
+</div>
 
-Parse cache location:
+## 📋 Supported Sources
 
-- `<platform-cache-root>/llm-usage-metrics/parse-file-cache.json` (defaults to `~/.cache/llm-usage-metrics/parse-file-cache.json` on Linux when `XDG_CACHE_HOME` is unset)
+| Source       | Pattern                           | Discovery                        |
+| ------------ | --------------------------------- | -------------------------------- |
+| **pi**       | `~/.pi/agent/sessions/**/*.jsonl` | Automatic                        |
+| **codex**    | `~/.codex/sessions/**/*.jsonl`    | Automatic                        |
+| **OpenCode** | `~/.opencode/opencode.db`         | Auto or explicit `--opencode-db` |
 
-Example:
+OpenCode source support requires Node.js 24+ runtime with built-in `node:sqlite`.
 
-```bash
-LLM_USAGE_PARSE_MAX_PARALLEL=16 LLM_USAGE_PRICING_FETCH_TIMEOUT_MS=8000 llm-usage monthly
-```
+## 🎯 Usage
 
-## Usage
-
-### Daily report (default terminal table)
+### Basic Reports
 
 ```bash
+# Daily report (default terminal table)
 llm-usage daily
-```
 
-### Weekly report with custom timezone
-
-```bash
+# Weekly with timezone
 llm-usage weekly --timezone Europe/Paris
-```
 
-### Monthly report with date range
-
-```bash
+# Monthly date range
 llm-usage monthly --since 2026-01-01 --until 2026-01-31
 ```
 
-### Markdown output
-
-```bash
-llm-usage daily --markdown
-```
-
-### JSON output
+### Output Formats
 
 ```bash
+# JSON for pipelines
 llm-usage daily --json
-```
 
-### Offline pricing (use cached LiteLLM pricing only)
+# Markdown for documentation
+llm-usage daily --markdown
 
-```bash
-llm-usage monthly --pricing-offline
+# Detailed per-model breakdown
+llm-usage monthly --per-model-columns
 ```
 
-### Override pricing URL
+### Efficiency Reports
 
 ```bash
-llm-usage monthly --pricing-url https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
-```
-
-Pricing behavior notes:
-
-- LiteLLM is the active pricing source.
-- explicit `costUsd: 0` events are re-priced from LiteLLM when model pricing is available.
-- if all contributing events in a row have unresolved cost, the row `Cost` is rendered as `-`.
-- if only part of a row cost is known, the row `Cost` is rendered as `~$...` to mark incomplete pricing.
-- when pricing cannot be loaded from LiteLLM (or cache in offline mode), report generation fails fast.
+# Daily efficiency in current repository
+llm-usage efficiency daily
 
-### Custom session directories
+# Weekly efficiency for a specific repository path
+llm-usage efficiency weekly --repo-dir /path/to/repo
 
-```bash
-llm-usage daily --pi-dir /path/to/pi/sessions --codex-dir /path/to/codex/sessions
+# Include merge commits and export JSON
+llm-usage efficiency monthly --include-merge-commits --json
 ```
 
-Or use generic source-id mapping (repeatable):
+Efficiency reports are repo-attributed: usage events are mapped to a Git repository root using source metadata (`cwd`/path info), and only events attributed to the selected repo are included in efficiency totals.
 
-```bash
-llm-usage daily --source-dir pi=/path/to/pi/sessions --source-dir codex=/path/to/codex/sessions
-```
+#### Reading efficiency output
 
-Directory override rules:
+- `Commits`, `+Lines`, `-Lines`, `ΔLines` come from local Git shortstat outcomes (for your configured Git author).
+- `Input`, `Output`, `Reasoning`, `Cache Read`, `Cache Write`, `Total`, and `Cost` come from repo-attributed usage events.
+- `All Tokens/Commit` uses `Total / Commits` and includes cache read/write tokens.
+- `Non-Cache/Commit` uses `(Input + Output + Reasoning) / Commits` and excludes cache read/write tokens.
+- `$/Commit` uses `Cost / Commits`.
+- `$/1k Lines` uses `Cost / (ΔLines / 1000)`.
+- `Commits/$` uses `Commits / Cost` (shown only when `Cost > 0`).
 
-- `--source-dir` is directory-only (currently `pi` and `codex`).
-- `--source-dir opencode=...` is invalid and points to `--opencode-db`.
-- `--opencode-db <path>` sets an explicit OpenCode SQLite DB path.
+Efficiency period rows are emitted only when both Git outcomes and repo-attributed usage signal exist for that period.
+When a denominator is zero, derived values in emitted rows render as `-`.  
+When pricing is incomplete, terminal/markdown output prefixes affected USD metrics with `~`.
 
-OpenCode DB override:
+For source-by-source comparisons, run the same report per source:
 
 ```bash
-llm-usage daily --opencode-db /path/to/opencode.db
+llm-usage efficiency monthly --repo-dir /path/to/repo --source pi
+llm-usage efficiency monthly --repo-dir /path/to/repo --source codex
+llm-usage efficiency monthly --repo-dir /path/to/repo --source opencode
 ```
 
-OpenCode path precedence:
-
-1. explicit `--opencode-db`
-2. deterministic OS-specific default path candidates
+Note: usage filters (`--source`, `--provider`, `--model`, `--pi-dir`, `--codex-dir`, `--opencode-db`, `--source-dir`) also constrain commit attribution: only commit days with matching repo-attributed usage events are counted.
 
-Backfill example from a historical DB snapshot:
+### Filtering
 
 ```bash
-llm-usage monthly --source opencode --opencode-db /archives/opencode-2026-01.db --since 2026-01-01 --until 2026-01-31
-```
-
-OpenCode safety notes:
-
-- OpenCode DB is opened in read-only mode
-- unreadable/missing explicit paths fail fast with actionable errors
-- OpenCode CLI is optional for troubleshooting and not required for runtime parsing
-
-### Filter by source (`--source`)
-
-Use `--source` to limit reports to one or more source ids.
-
-Supported source ids:
+# By source
+llm-usage monthly --source pi,codex
 
-- `pi`
-- `codex`
-- `opencode`
+# By provider
+llm-usage monthly --provider openai
 
-Behavior:
+# By model
+llm-usage monthly --model claude
 
-- repeatable or comma-separated (`--source pi --source codex` or `--source pi,codex`)
-- case-insensitive source id matching
-- unknown ids fail fast with a validation error
+# Combined filters
+llm-usage monthly --source opencode --provider openai --model gpt-4.1
+```
 
-Examples:
+### Custom Paths
 
 ```bash
-# only codex data
-llm-usage monthly --source codex
+# Custom directories
+llm-usage daily --source-dir pi=/path/to/pi --source-dir codex=/path/to/codex
 
-# only pi data
-llm-usage monthly --source pi
+# Explicit OpenCode database
+llm-usage daily --opencode-db /path/to/opencode.db
+```
 
-# only OpenCode data
-llm-usage monthly --source opencode
+### Offline Mode
 
-# multiple sources
-llm-usage monthly --source pi --source codex
-llm-usage monthly --source pi,codex
+```bash
+# Use cached pricing only
+llm-usage monthly --pricing-offline
 
-# OpenCode source with explicit DB path
-llm-usage monthly --source opencode --opencode-db /path/to/opencode.db
+# Continue even if pricing fetch fails
+llm-usage monthly --ignore-pricing-failures
 ```
 
-### Filter by provider (`--provider`)
-
-Use `--provider` to keep only events whose provider contains the filter text.
+## 🧪 Production Benchmarks
 
-Behavior:
+Benchmarked on **February 24, 2026** on a local production machine:
 
-- case-insensitive substring match
-- optional flag (when omitted, all providers are included)
-- works together with `--source` and `--model`
+- OS: CachyOS (Linux 6.19.2-2-cachyos)
+- CPU: Intel Core Ultra 9 185H (22 logical CPUs)
+- RAM: 62 GiB
+- Storage: NVMe SSD
 
-Examples:
+Compared commands:
 
 ```bash
-# all OpenAI-family providers
+ccusage-codex monthly
 llm-usage monthly --provider openai
-
-# GitHub Models providers
-llm-usage monthly --provider github
-
-# source + provider together
-llm-usage monthly --source codex --provider openai
 ```
 
-### Filter by model (`--model`)
-
-`--model` supports repeatable and comma-separated filters. Matching is case-insensitive.
-
-Per filter value:
+Timed benchmark summary (5 runs per scenario):
 
-- if an exact model id exists in the currently selected event set (after source/provider/date filtering), exact matching is used
-- otherwise, substring matching is used
+| Tool                                                    | Cache mode | Median (s) | Mean (s) |
+| ------------------------------------------------------- | ---------- | ---------: | -------: |
+| `ccusage-codex monthly`                                 | no cache   |     14.247 |   14.456 |
+| `ccusage-codex monthly --offline`                       | with cache |     14.043 |   14.268 |
+| `llm-usage monthly --provider openai`                   | no cache   |      4.192 |    4.196 |
+| `llm-usage monthly --provider openai --pricing-offline` | with cache |      0.793 |    0.784 |
 
-Examples:
+On this dataset and machine:
 
-```bash
-# substring match (all Claude-family models)
-llm-usage monthly --model claude
+- `llm-usage` is `3.40x` faster than `ccusage-codex` in no-cache mode.
+- `llm-usage` is `17.71x` faster than `ccusage-codex` in cached mode.
+- `llm-usage` improves `5.29x` with cache; `ccusage-codex` improves `1.01x`.
 
-# exact match when present
-llm-usage monthly --model claude-sonnet-4.5
+Full methodology, cache-mode definition, and scope caveats are documented in the Astro docs: [Benchmarks](https://ayagmar.github.io/llm-usage-metrics/benchmarks/).
 
-# multiple model filters
-llm-usage monthly --model claude --model gpt-5
-llm-usage monthly --model claude,gpt-5
+Re-run benchmark locally:
 
-# source + provider + model together
-llm-usage monthly --source opencode --provider openai --model gpt-4.1
+```bash
+pnpm run perf:production-benchmark -- --runs 5
 ```
 
-### Per-model columns (opt-in detailed table layout)
-
-Default output is compact (model names only in the Models column).
-
-Use `--per-model-columns` to render per-model multiline metrics in each numeric column:
+Generate machine-readable artifacts:
 
 ```bash
-llm-usage monthly --per-model-columns
-llm-usage monthly --markdown --per-model-columns
+pnpm run perf:production-benchmark -- \
+  --runs 5 \
+  --json-output ./tmp/production-benchmark.json \
+  --markdown-output ./tmp/production-benchmark.md
 ```
 
-## Output features
-
-### Terminal UI
+## ⚙️ Configuration
 
-The CLI provides an enhanced terminal output with:
+### Environment Variables
 
-- **Boxed report header** showing the report type and timezone
-- **Session summary** displayed at startup (session files and event counts per source)
-- **Malformed-row summary** when rows are skipped, including per-source reason counts
-- **Source failure summary** when one or more sources fail to parse
-- **Pricing source info** indicating whether data was loaded from cache or fetched remotely
-- **Environment variable overrides** displayed when active
-- **Models displayed as bullet points** for better readability
-- **Rounded table borders** and improved color scheme
+| Variable                         | Description                       |
+| -------------------------------- | --------------------------------- |
+| `LLM_USAGE_SKIP_UPDATE_CHECK`    | Skip update check (`1`)           |
+| `LLM_USAGE_PRICING_CACHE_TTL_MS` | Pricing cache duration            |
+| `LLM_USAGE_PARSE_MAX_PARALLEL`   | Max parallel file parses (`1-64`) |
+| `LLM_USAGE_PARSE_CACHE_ENABLED`  | Enable parse cache (`1/0`)        |
 
-Example output:
+See full environment variable reference in the [documentation](https://ayagmar.github.io/llm-usage-metrics/configuration/).
 
-```text
-ℹ Found 12 session file(s) with 45 event(s)
-•   pi: 8 file(s), 32 events
-•   codex: 4 file(s), 13 events
-ℹ Loaded pricing from cache
+### Update Checks
 
-┌────────────────────────────┐
-│ Monthly Token Usage Report │
-└────────────────────────────┘
+The CLI performs lightweight update checks with smart defaults:
 
-╭────────────┬──────────┬──────────────────────╮
-│ Period     │ Source   │ Models               │
-├────────────┼──────────┼──────────────────────┤
-│ Feb 2026   │ pi       │ • gpt-5.2            │
-│            │          │ • gpt-5.2-codex      │
-╰────────────┴──────────┴──────────────────────╯
-```
-
-### Report structure
-
-Each report includes:
+- 1-hour cache TTL
+- Skipped for `--help`, `--version`, and `npx` runs
+- Prompts only in interactive TTY sessions
 
-- source rows (`pi`, `codex`, `opencode`) for each period
-- a per-period combined subtotal row (only when multiple sources exist in that period)
-- a final grand total row across all periods
+Disable with:
 
-Columns:
-
-- Period
-- Source
-- Models
-- Input
-- Output
-- Reasoning
-- Cache Read
-- Cache Write
-- Total
-- Cost
+```bash
+LLM_USAGE_SKIP_UPDATE_CHECK=1 llm-usage daily
+```
 
-## Development
+## 🛠️ Development
 
 ```bash
+# Install dependencies
 pnpm install
+
+# Run quality checks
 pnpm run lint
 pnpm run typecheck
 pnpm run test
 pnpm run format:check
+
+# Build
+pnpm run build
+
+# Run locally
+pnpm cli daily
 ```
+
+## 📚 Documentation
+
+- **[Getting Started](https://ayagmar.github.io/llm-usage-metrics/getting-started/)** — Installation and first steps
+- **[CLI Reference](https://ayagmar.github.io/llm-usage-metrics/cli-reference/)** — Complete command reference
+- **[Efficiency](https://ayagmar.github.io/llm-usage-metrics/efficiency/)** — Efficiency report semantics and interpretation
+- **[Data Sources](https://ayagmar.github.io/llm-usage-metrics/sources/)** — Source configuration
+- **[Configuration](https://ayagmar.github.io/llm-usage-metrics/configuration/)** — Environment variables
+- **[Benchmarks](https://ayagmar.github.io/llm-usage-metrics/benchmarks/)** — Production benchmark methodology and results
+- **[Architecture](https://ayagmar.github.io/llm-usage-metrics/architecture/)** — Technical overview
+
+## 🤝 Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+The codebase is structured to add more sources through the `SourceAdapter` pattern.
+
+## 📄 License
+
+MIT © [Abdeslam Yagmar](https://github.com/ayagmar)