llm-usage-metrics 0.8.0 → 0.9.0

package/README.md

@@ -23,24 +23,29 @@
   <a href="./CONTRIBUTING.md">Contributing</a>
 </p>
 
-`llm-usage-metrics` reads local session data from 16 AI coding tools and converts it into one normalized usage history. Use it to review tokens and estimated cost, compare periods, find expensive sessions, correlate usage with local Git activity, or export the result.
+`llm-usage-metrics` reads local session data from 17 AI coding tools and converts it into one normalized usage history. Use it to review tokens and estimated cost, compare periods, find expensive sessions, correlate usage with local Git activity, or export the result.
 
 The CLI parses session content on your machine. It discovers standard source locations and includes a bundled pricing snapshot, so the first report can run without configuration or network access.
 
 ## Quick start
 
-Requires Node.js 24 or newer.
+Requires Node.js 22.16+ or 24+ (Node 23 lacks the SQLite busy timeout the ledger uses).
 
 ```bash
 # Run without installing
-npx --yes llm-usage-metrics@latest daily
+npx --yes llm-usage-metrics@latest
 
-# Or install the llm-usage command
+# Or install it: the package provides `llm-usage` and the alias `llm-usage-metrics`
 npm install -g llm-usage-metrics
-llm-usage daily
+llm-usage
+
+# Optional: tab completion (bash shown; zsh and fish work the same way)
+echo 'source <(llm-usage completion bash)' >> ~/.bashrc
 ```
 
-If the report is empty, check source discovery:
+With no command, `llm-usage` prints cost and tokens for today, the last 7 days, and month to date, a month-end projection (checked against `monthlyBudgetUsd` when you set one), what prompt caching saved you this month, then your current and longest streak, best day, and a year-long activity heatmap. `llm-usage daily` breaks the last 7 days down by day and source, and `llm-usage weekly` covers the last 8 weeks; add `--since YYYY-MM-DD` or `--all` for older usage.
+
+If the report is empty, check source discovery. `doctor` lists the paths each source searched and marks it found, not installed, or unparseable:
 
 ```bash
 llm-usage doctor
@@ -50,6 +55,7 @@ llm-usage doctor
 
 | Question                                                  | Command                                   |
 | --------------------------------------------------------- | ----------------------------------------- |
+| What did I spend today, this week, and this month?        | `llm-usage`                               |
 | How much did I use by day, week, or month?                | `llm-usage daily`, `weekly`, `monthly`    |
 | How did one period change from another?                   | `llm-usage compare`                       |
 | Which conversations or repositories used the most?        | `llm-usage session`                       |
@@ -57,6 +63,7 @@ llm-usage doctor
 | How does repo-attributed usage line up with Git activity? | `llm-usage efficiency monthly`            |
 | What would the same token mix cost on another model?      | `llm-usage optimize monthly`              |
 | What did the year add up to?                              | `llm-usage wrapped`                       |
+| What can my status bar show?                              | `llm-usage statusline`                    |
 | How do I get the raw normalized events out?               | `llm-usage events`                        |
 | Which sources and local stores are healthy?               | `llm-usage doctor`                        |
 | Which departed files can leave the event ledger?          | `llm-usage prune`                         |
@@ -69,7 +76,7 @@ Common examples:
 # A chosen calendar range
 llm-usage monthly --since 2026-06-01 --until 2026-06-30
 
-# Current local month compared with the previous month
+# Current month to date compared with the same days of the previous month
 llm-usage compare
 
 # Ten highest-cost conversations
@@ -87,6 +94,9 @@ llm-usage optimize monthly \
   --candidate-model gpt-4.1 \
   --candidate-model gpt-5-codex
 
+# One line for the Claude Code status line, tmux, or starship
+llm-usage statusline
+
 # Normalized events as JSONL, e.g. total tokens per line via jq
 llm-usage events --since 2026-06-01 | jq '.totalTokens'
 ```
@@ -111,6 +121,7 @@ llm-usage events --since 2026-06-01 | jq '.totalTokens'
 | RooCode                | task JSON     |
 | KiloCode               | task JSON     |
 | Antigravity            | SQLite        |
+| DeepSeek Harness       | JSONL + zstd  |
 
 Each source adapter owns discovery and source-specific token normalization. Reports operate on the same `UsageEvent` shape after parsing. The [source documentation](https://ayagmar.github.io/llm-usage-metrics/sources/) lists default paths, override flags, and adapter-specific semantics.
 
@@ -156,10 +167,10 @@ The pricing request never includes session content. See [Pricing](https://ayagma
 
 ## Local event ledger
 
-A SQLite event ledger stores normalized events and parse diagnostics. Unchanged files can skip parsing on later runs. The ledger also supports retained history for files that have left the disk:
+A SQLite event ledger stores normalized events and parse diagnostics. Unchanged files can skip parsing on later runs. Reports also include retained history for files that have left the disk (Claude Code, for example, deletes old transcripts), with moved or copied files suppressed. Leave it out with `--no-history`:
 
 ```bash
-llm-usage monthly --history
+llm-usage monthly --no-history
 ```
 
 `prune` is a dry run unless you pass `--apply`:
@@ -174,18 +185,21 @@ Deleting the ledger also deletes retained history. Read [Caching](https://ayagma
 ## Output
 
 ```bash
-llm-usage daily --json
+llm-usage daily --all --json
 llm-usage daily --markdown
+llm-usage daily --compact
 llm-usage monthly --share
 ```
 
-Report data goes to `stdout`. Discovery, pricing, config, and skipped-row diagnostics go to `stderr`, which keeps JSON and Markdown safe to redirect. JSON output is wrapped in a versioned envelope: `{ "schemaVersion": 1, "report": "usage", "data": ... }`. Scripts written against pre-0.8.0 JSON should follow the [migration guide](https://ayagmar.github.io/llm-usage-metrics/migrating-to-0-8/).
+Terminal tables fit the terminal width: on a narrow terminal, token counts are abbreviated and less-used columns are hidden, with a `stderr` note saying what was left out. `--compact` asks for the short table directly.
 
-Terminal, JSON, and Markdown availability varies by report. Usage, trends, wrapped, efficiency, and optimize can write supported share SVGs. The [output guide](https://ayagmar.github.io/llm-usage-metrics/output-formats/) contains the format matrix and file names.
+Report data goes to `stdout`. Diagnostics go to `stderr` as one summary line plus any warnings, which keeps JSON and Markdown safe to redirect; `--quiet` keeps only warnings and `--verbose` adds per-source and skipped-row detail. JSON output is wrapped in a versioned envelope: `{ "schemaVersion": 1, "report": "usage", "data": ... }`. Scripts written against pre-0.8.0 JSON should follow the [migration guide](https://ayagmar.github.io/llm-usage-metrics/migrating-to-0-8/).
+
+Terminal, JSON, and Markdown availability varies by report. Summary, usage, compare, trends, wrapped, efficiency, and optimize can write a 1200×630 share card: an SVG plus an HTML page that shows it in dark and light and exports a PNG in your browser. `--share --no-open` writes the files without opening the page. The [output guide](https://ayagmar.github.io/llm-usage-metrics/output-formats/) contains the format matrix and file names.
 
 ## Performance
 
-The repository publishes absolute cold and warm runtimes on real local corpora. The comparison includes the runs where `ccusage` is faster and the warm Claude run where the event ledger is faster. It also records the machine, commands, cache state, dataset size, and five-run distribution.
+The repository publishes direct-process and launcher-inclusive runtimes on stable snapshots of real local corpora. The current direct-process comparison shows `ccusage` ahead in every measured daily JSON cell; a separate monthly terminal check shows why timing `npx ccusage@...` can appear much slower than an installed `llm-usage` command. The benchmark records the machine, exact commands, application state, dataset size, and eight-run summary statistics.
 
 Read and reproduce the [benchmark](https://ayagmar.github.io/llm-usage-metrics/benchmarks/) before applying its results to another workload.
 
@@ -200,9 +214,12 @@ pnpm run format:check
 pnpm run build
 ```
 
+The website has a [docs overview](https://ayagmar.github.io/llm-usage-metrics/docs/) and a [report chooser](https://ayagmar.github.io/llm-usage-metrics/reports/) for finding the right command. Its landing page and source navigation use the CLI source registry; regenerate CLI and security references after behavior changes.
+
 Site commands:
 
 ```bash
+pnpm run site:docs:generate
 pnpm run site:check
 pnpm run site:build
 pnpm run site:dev