llm-usage-metrics 0.4.3 → 0.5.1

package/README.md

@@ -30,6 +30,7 @@ Aggregate token usage and costs from your local coding agent sessions. Supports
 - **Flexible Reports** — Daily, weekly, and monthly aggregations
 - **Efficiency Reports** — Correlate cost/tokens with repository commit outcomes
 - **Optimize Reports** — Counterfactual candidate-model pricing against observed token mix
+- **Trends Reports** — Daily cost or token trend views with combined or per-source output
 - **Multiple Outputs** — Terminal tables, JSON, or Markdown
 - **Smart Filtering** — By source, billing provider, model, and date ranges
 
@@ -97,6 +98,21 @@ llm-usage monthly --per-model-columns
 llm-usage monthly --share
 ```
 
+### Trends
+
+```bash
+# Last 30 local days of cost by default
+llm-usage trends
+
+# Token trends for the last 7 days
+llm-usage trends --metric tokens --days 7
+
+# Per-source trends in JSON
+llm-usage trends --by-source --json
+```
+
+Trends is terminal-first and supports `--json`. It does not support `--markdown` or `--share`.
+
 ### Efficiency Reports
 
 ```bash
@@ -119,8 +135,7 @@ Efficiency reports are repo-attributed: usage events are mapped to a Git reposit
 
 - `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.
+- `Tokens/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`).
@@ -275,12 +290,14 @@ pnpm run perf:production-benchmark -- \
 
 ### Environment Variables
 
-| 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`)        |
+| Variable                         | Description                        |
+| -------------------------------- | ---------------------------------- |
+| `LLM_USAGE_SKIP_UPDATE_CHECK`    | Skip update check (`1`)            |
+| `LLM_USAGE_UPDATE_CACHE_SCOPE`   | Update cache scope                 |
+| `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`)         |
+| `LLM_USAGE_PROFILE_RUNTIME`      | Emit runtime profiling diagnostics |
 
 Parse cache is source-sharded on disk (`parse-file-cache.<source>.json`) so source-scoped runs avoid loading unrelated cache blobs.
 
@@ -291,7 +308,9 @@ See full environment variable reference in the [documentation](https://ayagmar.g
 The CLI performs lightweight update checks with smart defaults:
 
 - 1-hour cache TTL
-- Skipped for `--help`, `--version`, and `npx` runs
+- Fresh cached update results are used immediately
+- Stale or missing cache refreshes in the background instead of blocking report execution
+- Skipped for `--help`, `--version`, `npx`, and direct source/development runs
 - Prompts only in interactive TTY sessions
 
 Disable with: