llm-usage-metrics 0.1.7 → 0.1.9

package/README.md

@@ -1,15 +1,23 @@
 # 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)
+
 CLI to aggregate local LLM usage from:
 
 - `~/.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.
 
 Project documentation is available in [`docs/`](./docs/README.md).
 
-Built-in adapters currently support `.pi` and `.codex`. The codebase is structured to add more sources (for example Claude/Gemini exports) through the `SourceAdapter` pattern. See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+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).
 
 ## Install
 
@@ -25,13 +33,20 @@ npx --yes llm-usage-metrics daily
 
 (`npx llm-usage daily` works when the project is already installed locally.)
 
+Runtime notes:
+
+- OpenCode parsing requires Node.js 24+ (`node:sqlite`).
+- Bun is supported for dependency/scripts workflow, but OpenCode report runs should use Node-based CLI execution.
+- Example local execution against built dist: `node dist/index.js daily --source opencode --opencode-db /path/to/opencode.db`
+
 ## Update checks
 
 When installed globally, the CLI performs a lightweight npm update check on startup.
 
 Behavior:
 
-- uses a local cache (`~/.cache/llm-usage-metrics/update-check.json`) with TTL
+- 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
@@ -48,7 +63,9 @@ LLM_USAGE_SKIP_UPDATE_CHECK=1 llm-usage daily
 You can tune runtime behavior with environment variables:
 
 - `LLM_USAGE_SKIP_UPDATE_CHECK`: skip startup update check when set to `1`
-- `LLM_USAGE_UPDATE_CACHE_TTL_MS`: update-check cache TTL in milliseconds (clamped: `60000..2592000000`)
+- `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`)
@@ -122,42 +139,105 @@ Or use generic source-id mapping (repeatable):
 llm-usage daily --source-dir pi=/path/to/pi/sessions --source-dir codex=/path/to/codex/sessions
 ```
 
-### Filter by source
+Directory override rules:
 
-Only codex rows:
+- `--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.
+
+OpenCode DB override:
 
 ```bash
-llm-usage monthly --source codex
+llm-usage daily --opencode-db /path/to/opencode.db
 ```
 
-Only pi rows:
+OpenCode path precedence:
+
+1. explicit `--opencode-db`
+2. deterministic OS-specific default path candidates
+
+Backfill example from a historical DB snapshot:
 
 ```bash
-llm-usage monthly --source pi
+llm-usage monthly --source opencode --opencode-db /archives/opencode-2026-01.db --since 2026-01-01 --until 2026-01-31
 ```
 
-Multiple sources (repeat or comma-separated):
+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:
+
+- `pi`
+- `codex`
+- `opencode`
+
+Behavior:
+
+- 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
+
+Examples:
 
 ```bash
+# only codex data
+llm-usage monthly --source codex
+
+# only pi data
+llm-usage monthly --source pi
+
+# only OpenCode data
+llm-usage monthly --source opencode
+
+# multiple sources
 llm-usage monthly --source pi --source codex
 llm-usage monthly --source pi,codex
+
+# OpenCode source with explicit DB path
+llm-usage monthly --source opencode --opencode-db /path/to/opencode.db
 ```
 
-### Filter by provider (optional)
+### Filter by provider (`--provider`)
+
+Use `--provider` to keep only events whose provider contains the filter text.
+
+Behavior:
+
+- case-insensitive substring match
+- optional flag (when omitted, all providers are included)
+- works together with `--source` and `--model`
+
+Examples:
 
 ```bash
+# all OpenAI-family providers
 llm-usage monthly --provider openai
+
+# GitHub Models providers
 llm-usage monthly --provider github
-llm-usage monthly --provider kimi
+
+# source + provider together
+llm-usage monthly --source codex --provider openai
 ```
 
-### Filter by model (optional)
+### Filter by model (`--model`)
+
+`--model` supports repeatable and comma-separated filters. Matching is case-insensitive.
 
-`--model` supports repeatable/comma-separated filters. Matching is case-insensitive.
+Per filter value:
 
-- if an exact model exists for a filter value, exact matching is used
+- 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
 
+Examples:
+
 ```bash
 # substring match (all Claude-family models)
 llm-usage monthly --model claude
@@ -165,9 +245,12 @@ llm-usage monthly --model claude
 # exact match when present
 llm-usage monthly --model claude-sonnet-4.5
 
-# multiple filters
+# multiple model filters
 llm-usage monthly --model claude --model gpt-5
 llm-usage monthly --model claude,gpt-5
+
+# source + provider + model together
+llm-usage monthly --source opencode --provider openai --model gpt-4.1
 ```
 
 ### Per-model columns (opt-in detailed table layout)
@@ -218,7 +301,7 @@ Example output:
 
 Each report includes:
 
-- source rows (`pi`, `codex`) for each period
+- 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