llm-usage-metrics 0.11.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +89 -43
- package/dist/bin.js +13 -2
- package/dist/index.js +40746 -22955
- package/package.json +26 -11
package/README.md
CHANGED
|
@@ -23,7 +23,11 @@
|
|
|
23
23
|
<a href="./CONTRIBUTING.md">Contributing</a>
|
|
24
24
|
</p>
|
|
25
25
|
|
|
26
|
-
`llm-usage-metrics` reads local session data from 17 AI coding tools, on this machine and on others you reach over ssh, and converts it into one normalized usage history. Use it to review tokens and estimated cost, compare periods,
|
|
26
|
+
`llm-usage-metrics` reads local session data from 17 AI coding tools, on this machine and on others you reach over ssh, and converts it into one normalized usage history. Use it to review tokens and estimated cost by day, hour, project or session, compare periods, check usage against 5-hour plan windows and subscription prices, correlate usage with local Git activity, explore it all in an interactive HTML report, or export the events.
|
|
27
|
+
|
|
28
|
+
<p align="center">
|
|
29
|
+
<img src="https://raw.githubusercontent.com/ayagmar/llm-usage-metrics/master/site/src/assets/screenshots/term-summary.webp" width="520" alt="llm-usage summary in a terminal: cost and tokens for today, the last 7 days and month to date, the month-end pace, prompt caching savings, streaks and a year-long activity heatmap">
|
|
30
|
+
</p>
|
|
27
31
|
|
|
28
32
|
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.
|
|
29
33
|
|
|
@@ -48,7 +52,7 @@ bunx --bun llm-usage-metrics@latest
|
|
|
48
52
|
echo 'source <(llm-usage completion bash)' >> ~/.bashrc
|
|
49
53
|
```
|
|
50
54
|
|
|
51
|
-
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.
|
|
55
|
+
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.
|
|
52
56
|
|
|
53
57
|
If the report is empty, check source discovery. `doctor` lists the paths each source searched and marks it found, not installed, or unparseable:
|
|
54
58
|
|
|
@@ -58,22 +62,31 @@ llm-usage doctor
|
|
|
58
62
|
|
|
59
63
|
## Reports
|
|
60
64
|
|
|
61
|
-
| Question | Command
|
|
62
|
-
| --------------------------------------------------------- |
|
|
63
|
-
| What did I spend today, this week, and this month? | `llm-usage`
|
|
64
|
-
| How much did I use by day, week, or month? | `llm-usage daily`, `weekly`, `monthly`
|
|
65
|
-
| How did
|
|
66
|
-
|
|
|
67
|
-
|
|
|
68
|
-
|
|
|
69
|
-
|
|
|
70
|
-
|
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
| Which
|
|
75
|
-
|
|
|
76
|
-
|
|
|
65
|
+
| Question | Command |
|
|
66
|
+
| --------------------------------------------------------- | ------------------------------------------------------ |
|
|
67
|
+
| What did I spend today, this week, and this month? | `llm-usage` |
|
|
68
|
+
| How much did I use by day, week, or month? | `llm-usage daily`, `weekly`, `monthly` |
|
|
69
|
+
| How did today go, hour by hour? | `llm-usage hourly` |
|
|
70
|
+
| How did one period change from another? | `llm-usage compare` |
|
|
71
|
+
| Which conversations or repositories used the most? | `llm-usage session` |
|
|
72
|
+
| What did each project cost? | `llm-usage projects` |
|
|
73
|
+
| Why did one session cost what it did? | `llm-usage session --id <id> --timeline` |
|
|
74
|
+
| Which sessions send the largest prompts? | `llm-usage context --by-session` |
|
|
75
|
+
| Which tools do my agents call, and which fail? | `llm-usage tools` |
|
|
76
|
+
| Which estimated 5-hour plan windows did I use? | `llm-usage blocks` |
|
|
77
|
+
| How does API-priced usage compare with my plan price? | `llm-usage value` |
|
|
78
|
+
| Which price does a model name get, and why? | `llm-usage pricing <model>` |
|
|
79
|
+
| How is daily usage moving? | `llm-usage trends` |
|
|
80
|
+
| How does repo-attributed usage line up with Git activity? | `llm-usage efficiency monthly` |
|
|
81
|
+
| What would the same token mix cost on another model? | `llm-usage optimize monthly --candidate-model <model>` |
|
|
82
|
+
| What did the year add up to? | `llm-usage wrapped` |
|
|
83
|
+
| Can I explore the numbers in a browser? | `llm-usage monthly --share` |
|
|
84
|
+
| What can my status bar show? | `llm-usage statusline` |
|
|
85
|
+
| How do I get the raw normalized events out? | `llm-usage events` |
|
|
86
|
+
| Which sources and local stores are healthy? | `llm-usage doctor` |
|
|
87
|
+
| Which departed files can leave the event ledger? | `llm-usage prune --suppressed` |
|
|
88
|
+
| Which settings apply, and where does each come from? | `llm-usage config show`, `config path` |
|
|
89
|
+
| Which JSON Schema does my installed version emit? | `llm-usage schema usage`, `schema --list` |
|
|
77
90
|
|
|
78
91
|
Common examples:
|
|
79
92
|
|
|
@@ -87,9 +100,28 @@ llm-usage compare
|
|
|
87
100
|
# Ten highest-cost conversations
|
|
88
101
|
llm-usage session --top 10
|
|
89
102
|
|
|
90
|
-
# Usage grouped by
|
|
103
|
+
# Usage grouped by project
|
|
91
104
|
llm-usage session --by-repo
|
|
92
105
|
|
|
106
|
+
# One session request by request, with its tool calls and running cost
|
|
107
|
+
llm-usage session --id 486c3261 --timeline
|
|
108
|
+
|
|
109
|
+
# Tool calls of the last 7 days, split by source
|
|
110
|
+
llm-usage tools --by-source
|
|
111
|
+
|
|
112
|
+
# Cost per project, and daily rows split by project
|
|
113
|
+
llm-usage projects --top 10
|
|
114
|
+
llm-usage daily --by-repo
|
|
115
|
+
|
|
116
|
+
# Estimated 5-hour blocks for Claude Code today, including the active one
|
|
117
|
+
llm-usage blocks --source claude --last 1
|
|
118
|
+
|
|
119
|
+
# API-priced cost per month against a subscription price
|
|
120
|
+
llm-usage value --plan claude-max-5x
|
|
121
|
+
|
|
122
|
+
# How a model name resolves to a LiteLLM price
|
|
123
|
+
llm-usage pricing claude-sonnet-4-5
|
|
124
|
+
|
|
93
125
|
# Last 14 local days as a token series
|
|
94
126
|
llm-usage trends --metric tokens --last 14
|
|
95
127
|
|
|
@@ -108,25 +140,27 @@ llm-usage events --since 2026-06-01 | jq '.totalTokens'
|
|
|
108
140
|
|
|
109
141
|
## Supported sources
|
|
110
142
|
|
|
111
|
-
| Source | Local format |
|
|
112
|
-
| ---------------------- | ------------- |
|
|
113
|
-
| pi | JSONL |
|
|
114
|
-
| codex | JSONL |
|
|
115
|
-
| Gemini CLI | JSON |
|
|
116
|
-
| Droid CLI | settings JSON |
|
|
117
|
-
| OpenCode | SQLite |
|
|
118
|
-
| OpenClaw | JSONL |
|
|
119
|
-
| Claude Code | JSONL |
|
|
120
|
-
| GitHub Copilot CLI | OTEL JSONL |
|
|
121
|
-
| Goose | SQLite |
|
|
122
|
-
| Amp | JSON |
|
|
123
|
-
| Qwen CLI | JSONL |
|
|
124
|
-
| Kimi CLI and Kimi Code | wire JSONL |
|
|
125
|
-
| Cline | task JSON |
|
|
126
|
-
| RooCode | task JSON |
|
|
127
|
-
| KiloCode | task JSON |
|
|
128
|
-
| Antigravity | SQLite |
|
|
129
|
-
| DeepSeek Harness | JSONL + zstd |
|
|
143
|
+
| Source | Local format | Real logs |
|
|
144
|
+
| ---------------------- | ------------- | --------- |
|
|
145
|
+
| pi | JSONL | checked |
|
|
146
|
+
| codex | JSONL | checked |
|
|
147
|
+
| Gemini CLI | JSON | checked |
|
|
148
|
+
| Droid CLI | settings JSON | not yet |
|
|
149
|
+
| OpenCode | SQLite | checked |
|
|
150
|
+
| OpenClaw | JSONL | not yet |
|
|
151
|
+
| Claude Code | JSONL | checked |
|
|
152
|
+
| GitHub Copilot CLI | OTEL JSONL | not yet |
|
|
153
|
+
| Goose | SQLite | not yet |
|
|
154
|
+
| Amp | JSON | not yet |
|
|
155
|
+
| Qwen CLI | JSONL | not yet |
|
|
156
|
+
| Kimi CLI and Kimi Code | wire JSONL | not yet |
|
|
157
|
+
| Cline | task JSON | not yet |
|
|
158
|
+
| RooCode | task JSON | not yet |
|
|
159
|
+
| KiloCode | task JSON | not yet |
|
|
160
|
+
| Antigravity | SQLite | checked |
|
|
161
|
+
| DeepSeek Harness | JSONL + zstd | not yet |
|
|
162
|
+
|
|
163
|
+
In the Real logs column, _checked_ means the adapter was compared with real logs from that tool; _not yet_ means it is built from the tool's upstream code and synthetic fixtures. If a report disagrees with your tool, [open an issue](https://github.com/ayagmar/llm-usage-metrics/issues) with the `llm-usage doctor --source <source>` output; leave out log contents.
|
|
130
164
|
|
|
131
165
|
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.
|
|
132
166
|
|
|
@@ -144,6 +178,9 @@ llm-usage monthly --provider openai
|
|
|
144
178
|
# Filter by exact model or substring
|
|
145
179
|
llm-usage monthly --model codex
|
|
146
180
|
|
|
181
|
+
# Filter by project: a path matches that root and the roots under it, a name matches the end of a root
|
|
182
|
+
llm-usage monthly --repo ~/work/api --repo web
|
|
183
|
+
|
|
147
184
|
# Create a commented TOML config with editor schema support
|
|
148
185
|
llm-usage config init
|
|
149
186
|
```
|
|
@@ -154,7 +191,7 @@ The config precedence order is CLI flags, environment variables, TOML config, th
|
|
|
154
191
|
|
|
155
192
|
## Pricing
|
|
156
193
|
|
|
157
|
-
The CLI keeps a valid cost supplied by a source. When a source has no cost, it estimates one from LiteLLM pricing.
|
|
194
|
+
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.
|
|
158
195
|
|
|
159
196
|
Pricing loads from a fresh cache, a network refresh, a stale cache, or the bundled snapshot. Use offline mode to skip the network request:
|
|
160
197
|
|
|
@@ -212,15 +249,24 @@ llm-usage monthly --share
|
|
|
212
249
|
llm-usage weekly --last 1 --no-cost
|
|
213
250
|
```
|
|
214
251
|
|
|
215
|
-
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
|
|
252
|
+
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.
|
|
253
|
+
|
|
254
|
+
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/).
|
|
255
|
+
|
|
256
|
+
<picture>
|
|
257
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ayagmar/llm-usage-metrics/master/site/src/assets/screenshots/share-daily-dark.webp">
|
|
258
|
+
<img src="https://raw.githubusercontent.com/ayagmar/llm-usage-metrics/master/site/src/assets/screenshots/share-daily-light.webp" alt="The interactive report from llm-usage daily --share: period, grouping, source, model and project filters, totals for tokens, cost, events and active time, and a daily cost chart stacked by source">
|
|
259
|
+
</picture>
|
|
260
|
+
|
|
261
|
+
Terminal, JSON, and Markdown availability varies by report. Summary, usage, compare, trends, wrapped, efficiency, and optimize can write a share report with `--share`: one self-contained HTML file with charts, filters, sortable tables, and a drill-down from projects to sessions, that exports each chart as PNG or SVG in your browser and loads nothing from the network. `--redact` replaces project, machine and local model names in the file, and `--share --no-open` writes it without opening it. The [output guide](https://ayagmar.github.io/llm-usage-metrics/output-formats/) contains the format matrix and file names.
|
|
216
262
|
|
|
217
|
-
|
|
263
|
+
## Library
|
|
218
264
|
|
|
219
|
-
|
|
265
|
+
The parsers behind the CLI are a separate package, `@ayagmar/agent-sessions`, for Node.js scripts and tools that want the same events without pricing, the ledger or reports. It reads all 17 sources into one event shape (token usage, and for Claude Code, codex and pi also messages, tool calls and session facts), has no runtime dependencies, and never touches the network. It is not on npm yet. See the [library docs](https://ayagmar.github.io/llm-usage-metrics/library/) for how to build it from this repository and use it.
|
|
220
266
|
|
|
221
267
|
## Performance
|
|
222
268
|
|
|
223
|
-
The repository publishes
|
|
269
|
+
The repository publishes runtimes for `llm-usage` and `ccusage` on stable snapshots of real local logs. Since ccusage 20.0.0 moved to a native binary behind a small Node launcher, this compares Node against native code. In the October 2026 run, ccusage was faster on Codex `daily --json` and `llm-usage` was faster on Claude Code `daily --json`. A separate monthly terminal check shows how much `npx ccusage@...` adds at the shell. The page records the machine, versions, exact commands, application state, dataset size and run counts.
|
|
224
270
|
|
|
225
271
|
Read and reproduce the [benchmark](https://ayagmar.github.io/llm-usage-metrics/benchmarks/) before applying its results to another workload.
|
|
226
272
|
|
package/dist/bin.js
CHANGED
|
@@ -2,6 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
// src/cli/bin.ts
|
|
4
4
|
import module from "module";
|
|
5
|
-
|
|
6
|
-
|
|
5
|
+
var [nodeMajor = 0, nodeMinor = 0] = process.versions.node.split(".").map(Number);
|
|
6
|
+
var isSupportedRuntime = process.versions.bun !== void 0 || nodeMajor >= 24 || nodeMajor === 22 && nodeMinor >= 16;
|
|
7
|
+
if (isSupportedRuntime) {
|
|
8
|
+
if (typeof module.enableCompileCache === "function") {
|
|
9
|
+
module.enableCompileCache();
|
|
10
|
+
}
|
|
11
|
+
await import(new URL("./index.js", import.meta.url).href);
|
|
12
|
+
} else {
|
|
13
|
+
console.error(
|
|
14
|
+
`llm-usage requires Node.js 22.16+ or 24+; this is Node.js ${process.versions.node}.`
|
|
15
|
+
);
|
|
16
|
+
process.exitCode = 1;
|
|
17
|
+
}
|
|
7
18
|
//# sourceMappingURL=bin.js.map
|