llm-usage-metrics 0.12.1 → 0.14.0

package/README.md

@@ -54,7 +54,7 @@ echo 'source <(llm-usage completion bash)' >> ~/.bashrc
 
 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, a note when a day of the last 7 cost at least $1 and at least 3 times your median active day, 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:
+If the report is empty, check source discovery. `doctor` marks each source found, not installed, or unparseable and lists the paths it searched (`--verbose` adds the paths of sources that are not installed):
 
 ```bash
 llm-usage doctor
@@ -109,8 +109,9 @@ llm-usage session --id 486c3261 --timeline
 # Tool calls of the last 7 days, split by source
 llm-usage tools --by-source
 
-# Cost per project, and daily rows split by project
-llm-usage projects --top 10
+# Cost per project (the directory each session started in, so a cd into a subfolder
+# stays with it, and a git worktree counts for its repository), and daily rows split by project
+llm-usage projects
 llm-usage daily --by-repo
 
 # Estimated 5-hour blocks for Claude Code today, including the active one
@@ -143,7 +144,7 @@ llm-usage events --since 2026-06-01 | jq '.totalTokens'
 | Source                 | Local format  | Real logs |
 | ---------------------- | ------------- | --------- |
 | pi                     | JSONL         | checked   |
-| codex                  | JSONL         | checked   |
+| codex                  | JSONL + zstd  | checked   |
 | Gemini CLI             | JSON          | checked   |
 | Droid CLI              | settings JSON | not yet   |
 | OpenCode               | SQLite        | checked   |
@@ -191,7 +192,7 @@ The config precedence order is CLI flags, environment variables, TOML config, th
 
 ## Pricing
 
-The CLI keeps a valid cost supplied by a source. When a source has no cost, it estimates one from LiteLLM pricing. A source that logs `$0` for a request that used tokens gets an estimate too, and stderr names those sources. `--cost-mode explicit` reports logged costs only and keeps `$0`; `--cost-mode estimated` prices every event from its tokens.
+The CLI keeps a valid cost supplied by a source. When a source has no cost, it estimates one from LiteLLM pricing. A source that logs `$0` for a request that used tokens gets an estimate too, and `--verbose` names those sources on stderr. `--cost-mode explicit` reports logged costs only and keeps `$0`; `--cost-mode estimated` prices every event from its tokens.
 
 Pricing loads from a fresh cache, a network refresh, a stale cache, or the bundled snapshot. Use offline mode to skip the network request:
 
@@ -217,9 +218,10 @@ A SQLite event ledger stores normalized events and parse diagnostics. Unchanged
 llm-usage monthly --no-history
 ```
 
-`prune` is a dry run unless you pass `--apply`:
+`prune` is a dry run unless you pass `--apply`. Run it without a selector to count what each selector would pick:
 
 ```bash
+llm-usage prune
 llm-usage prune --suppressed
 llm-usage prune --departed-before 2026-01-01 --apply
 ```
@@ -239,6 +241,16 @@ llm-usage                            # the summary splits this month's cost by m
 
 A session that reached both machines (a copied or synced `~/.claude`) is counted once. See [Multiple machines](https://ayagmar.github.io/llm-usage-metrics/machines/).
 
+## Use with coding agents
+
+The repository ships an agent skill that teaches Claude Code, Codex, Pi, and other agents which `llm-usage` command answers a spend or usage question, and to read the `--json` output instead of guessing. Install it with the [skills CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add ayagmar/llm-usage-metrics --skill llm-usage-metrics --agent claude-code
+```
+
+Use `--agent codex`, `--agent pi`, or another agent id, and `-g` to install it for all projects. See [Use with coding agents](https://ayagmar.github.io/llm-usage-metrics/agents/).
+
 ## Output
 
 ```bash
@@ -251,7 +263,7 @@ llm-usage weekly --last 1 --no-cost
 
 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. When no table fits, as on a phone, each row is listed as labelled values instead. `--compact` asks for the short table directly. `--last N` covers the last N days, weeks, or months, counting the current one, and `--no-cost` leaves spend out of tables and share reports.
 
-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/upgrading/0-8/).
+Report data goes to `stdout`. Diagnostics go to `stderr`, which keeps JSON and Markdown safe to redirect. By default that is warnings and the notes that explain the numbers, such as the `~` cost marker; `--quiet` keeps only warnings, and `--verbose` adds the scan summary, history and machine notes, and 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/upgrading/0-8/).
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ayagmar/llm-usage-metrics/master/site/src/assets/screenshots/share-daily-dark.webp">

package/dist/bin.js

@@ -1,18 +1,3 @@
 #!/usr/bin/env node
-
-// src/cli/bin.ts
-import module from "module";
-var [nodeMajor = 0, nodeMinor = 0] = process.versions.node.split(".").map(Number);
-var isSupportedRuntime = process.versions.bun !== void 0 || nodeMajor >= 24 || nodeMajor === 22 && nodeMinor >= 16;
-if (isSupportedRuntime) {
-  if (typeof module.enableCompileCache === "function") {
-    module.enableCompileCache();
-  }
-  await import(new URL("./index.js", import.meta.url).href);
-} else {
-  console.error(
-    `llm-usage requires Node.js 22.16+ or 24+; this is Node.js ${process.versions.node}.`
-  );
-  process.exitCode = 1;
-}
+import e from"module";var[o=0,s=0]=process.versions.node.split(".").map(Number),n=process.versions.bun!==void 0||o>=24||o===22&&s>=16;n?(typeof e.enableCompileCache=="function"&&e.enableCompileCache(),await import(new URL("./index.js",import.meta.url).href)):(console.error(`llm-usage requires Node.js 22.16+ or 24+; this is Node.js ${process.versions.node}.`),process.exitCode=1);
 //# sourceMappingURL=bin.js.map