llm-usage-metrics 0.3.4 → 0.3.6

package/README.md

@@ -21,11 +21,11 @@
 
 ---
 
-Aggregate token usage and costs from your local coding agent sessions. Supports **pi**, **codex**, **Gemini CLI**, and **OpenCode** with zero configuration required.
+Aggregate token usage and costs from your local coding agent sessions. Supports **pi**, **codex**, **Gemini CLI**, **Droid CLI**, and **OpenCode** with zero configuration required.
 
 ## ✨ Features
 
-- **Zero-Config Discovery** — Automatically finds `.pi`, `.codex`, `.gemini`, and OpenCode session data
+- **Zero-Config Discovery** — Automatically finds `.pi`, `.codex`, `.gemini`, `.factory`, 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
@@ -39,7 +39,7 @@ Aggregate token usage and costs from your local coding agent sessions. Supports
 npm install -g llm-usage-metrics
 
 # Or run without installing
-npx llm-usage-metrics daily
+npx llm-usage-metrics@latest daily
 
 # Generate your first report
 llm-usage daily
@@ -53,15 +53,18 @@ llm-usage daily
 
 ## 📋 Supported Sources
 
-| Source         | Pattern                           | Discovery                        |
-| -------------- | --------------------------------- | -------------------------------- |
-| **pi**         | `~/.pi/agent/sessions/**/*.jsonl` | Automatic                        |
-| **codex**      | `~/.codex/sessions/**/*.jsonl`    | Automatic                        |
-| **Gemini CLI** | `~/.gemini/tmp/*/chats/*.json`    | Automatic                        |
-| **OpenCode**   | `~/.opencode/opencode.db`         | Auto or explicit `--opencode-db` |
+| Source         | Pattern                                  | Discovery                        |
+| -------------- | ---------------------------------------- | -------------------------------- |
+| **pi**         | `~/.pi/agent/sessions/**/*.jsonl`        | Automatic                        |
+| **codex**      | `~/.codex/sessions/**/*.jsonl`           | Automatic                        |
+| **Gemini CLI** | `~/.gemini/tmp/*/chats/*.json`           | Automatic                        |
+| **Droid CLI**  | `~/.factory/sessions/**/*.settings.json` | Automatic                        |
+| **OpenCode**   | `~/.opencode/opencode.db`                | Auto or explicit `--opencode-db` |
 
 OpenCode source support requires Node.js 24+ runtime with built-in `node:sqlite`.
 
+For `droid`, `Input`, `Output`, `Reasoning`, `Cache Read`, and `Cache Write` come directly from session files, and `totalTokens` is billable raw tokens (`Input + Output + Cache Read + Cache Write`, excluding `Reasoning`). Factory dashboard totals may differ because Factory applies standard-token normalization/multipliers.
+
 ## 🎯 Usage
 
 ### Basic Reports
@@ -125,16 +128,17 @@ For source-by-source comparisons, run the same report per source:
 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 gemini
+llm-usage efficiency monthly --repo-dir /path/to/repo --source droid
 llm-usage efficiency monthly --repo-dir /path/to/repo --source opencode
 ```
 
-Note: usage filters (`--source`, `--provider`, `--model`, `--pi-dir`, `--codex-dir`, `--gemini-dir`, `--opencode-db`, `--source-dir`) also constrain commit attribution: only commit days with matching repo-attributed usage events are counted.
+Note: usage filters (`--source`, `--provider`, `--model`, `--pi-dir`, `--codex-dir`, `--gemini-dir`, `--droid-dir`, `--opencode-db`, `--source-dir`) also constrain commit attribution: only commit days with matching repo-attributed usage events are counted.
 
 ### Filtering
 
 ```bash
 # By source
-llm-usage monthly --source pi,codex,gemini
+llm-usage monthly --source pi,codex,gemini,droid
 
 # By provider
 llm-usage monthly --provider openai
@@ -150,10 +154,11 @@ llm-usage monthly --source opencode --provider openai --model gpt-4.1
 
 ```bash
 # Custom directories
-llm-usage daily --source-dir pi=/path/to/pi --source-dir codex=/path/to/codex --source-dir gemini=/path/to/.gemini
+llm-usage daily --source-dir pi=/path/to/pi --source-dir codex=/path/to/codex --source-dir gemini=/path/to/.gemini --source-dir droid=/path/to/.factory/sessions
 
-# Explicit Gemini/OpenCode paths
+# Explicit Gemini/Droid/OpenCode paths
 llm-usage daily --gemini-dir /path/to/.gemini
+llm-usage daily --droid-dir /path/to/.factory/sessions
 llm-usage daily --opencode-db /path/to/opencode.db
 ```
 
@@ -169,41 +174,61 @@ llm-usage monthly --ignore-pricing-failures
 
 ## 🧪 Production Benchmarks
 
-Benchmarked on **February 24, 2026** on a local production machine:
+Benchmarked on **February 27, 2026** on a local production machine:
 
 - OS: CachyOS (Linux 6.19.2-2-cachyos)
 - CPU: Intel Core Ultra 9 185H (22 logical CPUs)
 - RAM: 62 GiB
 - Storage: NVMe SSD
 
-Compared commands:
+Compared scenarios:
 
 ```bash
+# direct source-to-source parity (openai provider)
 ccusage-codex monthly
-llm-usage monthly --provider openai
+llm-usage monthly --provider openai --source codex
+
+# multi-source comparison for one provider (openai)
+ccusage-codex monthly
+llm-usage monthly --provider openai --source pi,codex,gemini,opencode
 ```
 
-Timed benchmark summary (5 runs per scenario):
+Timed benchmark summary (5 runs per scenario).
 
-| 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 |
+Direct source-to-source parity (`--source codex`):
 
-On this dataset and machine:
+| Tool                                                                   | Cache mode | Median (s) | Mean (s) |
+| ---------------------------------------------------------------------- | ---------- | ---------: | -------: |
+| `ccusage-codex monthly`                                                | no cache   |     16.785 |   17.288 |
+| `ccusage-codex monthly --offline`                                      | with cache |     16.995 |   17.594 |
+| `llm-usage monthly --provider openai --source codex`                   | no cache   |      3.651 |    3.760 |
+| `llm-usage monthly --provider openai --source codex --pricing-offline` | with cache |      0.746 |    0.724 |
 
-- `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`.
+Speedups (median): `4.60x` faster cold, `22.78x` faster cached.
+
+Multi-source OpenAI (`--source pi,codex,gemini,opencode`):
+
+| Tool                                                                                      | Cache mode | Median (s) | Mean (s) |
+| ----------------------------------------------------------------------------------------- | ---------- | ---------: | -------: |
+| `ccusage-codex monthly`                                                                   | no cache   |     17.297 |   17.463 |
+| `ccusage-codex monthly --offline`                                                         | with cache |     16.698 |   16.745 |
+| `llm-usage monthly --provider openai --source pi,codex,gemini,opencode`                   | no cache   |      4.767 |    4.864 |
+| `llm-usage monthly --provider openai --source pi,codex,gemini,opencode --pricing-offline` | with cache |      0.941 |    0.951 |
+
+Speedups (median): `3.63x` faster cold, `17.75x` faster cached.
 
 Full methodology, cache-mode definition, and scope caveats are documented in the Astro docs: [Benchmarks](https://ayagmar.github.io/llm-usage-metrics/benchmarks/).
 
-Re-run benchmark locally:
+Re-run direct parity benchmark locally:
 
 ```bash
-pnpm run perf:production-benchmark -- --runs 5
+pnpm run perf:production-benchmark -- --runs 5 --llm-source codex
+```
+
+Re-run multi-source OpenAI benchmark locally:
+
+```bash
+pnpm run perf:production-benchmark -- --runs 5 --llm-source pi,codex,gemini,opencode
 ```
 
 Generate machine-readable artifacts:
@@ -211,8 +236,15 @@ Generate machine-readable artifacts:
 ```bash
 pnpm run perf:production-benchmark -- \
   --runs 5 \
-  --json-output ./tmp/production-benchmark.json \
-  --markdown-output ./tmp/production-benchmark.md
+  --llm-source codex \
+  --json-output ./tmp/production-benchmark-openai-codex.json \
+  --markdown-output ./tmp/production-benchmark-openai-codex.md
+
+pnpm run perf:production-benchmark -- \
+  --runs 5 \
+  --llm-source pi,codex,gemini,opencode \
+  --json-output ./tmp/production-benchmark-openai-multi-source.json \
+  --markdown-output ./tmp/production-benchmark-openai-multi-source.md
 ```
 
 ## ⚙️ Configuration
@@ -226,6 +258,8 @@ pnpm run perf:production-benchmark -- \
 | `LLM_USAGE_PARSE_MAX_PARALLEL`   | Max parallel file parses (`1-64`) |
 | `LLM_USAGE_PARSE_CACHE_ENABLED`  | Enable parse cache (`1/0`)        |
 
+Parse cache is source-sharded on disk (`parse-file-cache.<source>.json`) so source-scoped runs avoid loading unrelated cache blobs.
+
 See full environment variable reference in the [documentation](https://ayagmar.github.io/llm-usage-metrics/configuration/).
 
 ### Update Checks