llm-usage-metrics 0.7.2 → 0.8.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 +130 -291
- package/dist/index.js +29466 -9167
- package/package.json +26 -10
- package/dist/index.d.ts +0 -1
- package/dist/index.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,376 +1,215 @@
|
|
|
1
|
-
<
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://ayagmar.github.io/llm-usage-metrics/favicon.svg" width="72" height="72" alt="LLM Usage Metrics logo">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
<
|
|
5
|
+
<h1 align="center">llm-usage-metrics</h1>
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
<p align="center">
|
|
8
|
+
Local usage reports for AI coding tools.
|
|
9
|
+
</p>
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="https://www.npmjs.com/package/llm-usage-metrics"><img src="https://img.shields.io/npm/v/llm-usage-metrics.svg?style=flat-square&color=b65331" alt="npm version"></a>
|
|
13
|
+
<a href="https://www.npmjs.com/package/llm-usage-metrics"><img src="https://img.shields.io/npm/dt/llm-usage-metrics.svg?style=flat-square&color=5f655b" alt="npm downloads"></a>
|
|
14
|
+
<a href="https://github.com/ayagmar/llm-usage-metrics/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ayagmar/llm-usage-metrics/ci.yml?style=flat-square&label=CI" alt="CI status"></a>
|
|
15
|
+
<a href="https://codecov.io/gh/ayagmar/llm-usage-metrics"><img src="https://img.shields.io/codecov/c/github/ayagmar/llm-usage-metrics?style=flat-square" alt="test coverage"></a>
|
|
16
|
+
<a href="https://deepwiki.com/ayagmar/llm-usage-metrics"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
|
|
17
|
+
</p>
|
|
8
18
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
19
|
+
<p align="center">
|
|
20
|
+
<a href="https://ayagmar.github.io/llm-usage-metrics/">Documentation</a> ·
|
|
21
|
+
<a href="https://ayagmar.github.io/llm-usage-metrics/getting-started/">Getting started</a> ·
|
|
22
|
+
<a href="https://ayagmar.github.io/llm-usage-metrics/cli-reference/">CLI reference</a> ·
|
|
23
|
+
<a href="./CONTRIBUTING.md">Contributing</a>
|
|
24
|
+
</p>
|
|
14
25
|
|
|
15
|
-
|
|
16
|
-
[⚡ Quick Start](#quick-start) ·
|
|
17
|
-
[📊 Examples](#usage) ·
|
|
18
|
-
[🤝 Contributing](./CONTRIBUTING.md)
|
|
26
|
+
`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.
|
|
19
27
|
|
|
20
|
-
|
|
28
|
+
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.
|
|
21
29
|
|
|
22
|
-
|
|
30
|
+
## Quick start
|
|
23
31
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
## ✨ Features
|
|
27
|
-
|
|
28
|
-
- **Zero-Config Discovery** — Automatically finds `.pi`, `.codex`, `.gemini`, `.factory`, OpenCode, OpenClaw, and Claude session data
|
|
29
|
-
- **LiteLLM Pricing** — Real-time pricing sync with offline caching support
|
|
30
|
-
- **Flexible Reports** — Daily, weekly, and monthly aggregations
|
|
31
|
-
- **Efficiency Reports** — Correlate cost/tokens with repository commit outcomes
|
|
32
|
-
- **Optimize Reports** — Counterfactual candidate-model pricing against observed token mix
|
|
33
|
-
- **Trends Reports** — Daily cost or token trend views with combined or per-source output
|
|
34
|
-
- **Multiple Outputs** — Terminal tables, JSON, or Markdown
|
|
35
|
-
- **Smart Filtering** — By source, billing provider, model, and date ranges
|
|
36
|
-
|
|
37
|
-
## 🚀 Quick Start
|
|
32
|
+
Requires Node.js 24 or newer.
|
|
38
33
|
|
|
39
34
|
```bash
|
|
40
|
-
#
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
# Or run without installing
|
|
44
|
-
npx llm-usage-metrics@latest daily
|
|
35
|
+
# Run without installing
|
|
36
|
+
npx --yes llm-usage-metrics@latest daily
|
|
45
37
|
|
|
46
|
-
#
|
|
38
|
+
# Or install the llm-usage command
|
|
39
|
+
npm install -g llm-usage-metrics
|
|
47
40
|
llm-usage daily
|
|
48
41
|
```
|
|
49
42
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
</div>
|
|
55
|
-
|
|
56
|
-
## 📋 Supported Sources
|
|
57
|
-
|
|
58
|
-
| Source | Pattern | Discovery |
|
|
59
|
-
| --------------- | ---------------------------------------- | -------------------------------- |
|
|
60
|
-
| **pi** | `~/.pi/agent/sessions/**/*.jsonl` | Automatic |
|
|
61
|
-
| **codex** | `~/.codex/sessions/**/*.jsonl` | Automatic |
|
|
62
|
-
| **Gemini CLI** | `~/.gemini/tmp/*/chats/*.json` | Automatic |
|
|
63
|
-
| **Droid CLI** | `~/.factory/sessions/**/*.settings.json` | Automatic |
|
|
64
|
-
| **OpenCode** | `~/.opencode/opencode.db` | Auto or explicit `--opencode-db` |
|
|
65
|
-
| **OpenClaw** | `~/.openclaw/agents/**/*.jsonl` | Automatic |
|
|
66
|
-
| **Claude Code** | `~/.claude/projects/**/*.jsonl` | Automatic |
|
|
67
|
-
|
|
68
|
-
OpenCode source support requires Node.js 24+ runtime with built-in `node:sqlite`.
|
|
69
|
-
|
|
70
|
-
For `droid`, `Input`, `Output`, `Reasoning`, `Cache Read`, and `Cache Write` come directly from session files, and `totalTokens` is billable raw tokens (`Input + Output + Cache Read + Cache Write`, excluding `Reasoning`). Factory dashboard totals may differ because Factory applies standard-token normalization/multipliers.
|
|
71
|
-
|
|
72
|
-
## 🎯 Usage
|
|
73
|
-
|
|
74
|
-
### Basic Reports
|
|
43
|
+
If the report is empty, check source discovery:
|
|
75
44
|
|
|
76
45
|
```bash
|
|
77
|
-
|
|
78
|
-
llm-usage daily
|
|
79
|
-
|
|
80
|
-
# Weekly with timezone
|
|
81
|
-
llm-usage weekly --timezone Europe/Paris
|
|
82
|
-
|
|
83
|
-
# Monthly date range
|
|
84
|
-
llm-usage monthly --since 2026-01-01 --until 2026-01-31
|
|
46
|
+
llm-usage doctor
|
|
85
47
|
```
|
|
86
48
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
```bash
|
|
90
|
-
# JSON for pipelines
|
|
91
|
-
llm-usage daily --json
|
|
92
|
-
|
|
93
|
-
# Markdown for documentation
|
|
94
|
-
llm-usage daily --markdown
|
|
95
|
-
|
|
96
|
-
# Detailed per-model breakdown
|
|
97
|
-
llm-usage monthly --per-model-columns
|
|
98
|
-
|
|
99
|
-
# Write a share SVG image
|
|
100
|
-
llm-usage monthly --share
|
|
101
|
-
```
|
|
49
|
+
## Reports
|
|
102
50
|
|
|
103
|
-
|
|
51
|
+
| Question | Command |
|
|
52
|
+
| --------------------------------------------------------- | ----------------------------------------- |
|
|
53
|
+
| How much did I use by day, week, or month? | `llm-usage daily`, `weekly`, `monthly` |
|
|
54
|
+
| How did one period change from another? | `llm-usage compare` |
|
|
55
|
+
| Which conversations or repositories used the most? | `llm-usage session` |
|
|
56
|
+
| How is daily usage moving? | `llm-usage trends` |
|
|
57
|
+
| How does repo-attributed usage line up with Git activity? | `llm-usage efficiency monthly` |
|
|
58
|
+
| What would the same token mix cost on another model? | `llm-usage optimize monthly` |
|
|
59
|
+
| What did the year add up to? | `llm-usage wrapped` |
|
|
60
|
+
| How do I get the raw normalized events out? | `llm-usage events` |
|
|
61
|
+
| Which sources and local stores are healthy? | `llm-usage doctor` |
|
|
62
|
+
| Which departed files can leave the event ledger? | `llm-usage prune` |
|
|
63
|
+
| What configuration is active, and which file is it from? | `llm-usage config show`, `config path` |
|
|
64
|
+
| Which JSON Schema does my installed version emit? | `llm-usage schema usage`, `schema --list` |
|
|
104
65
|
|
|
105
|
-
|
|
66
|
+
Common examples:
|
|
106
67
|
|
|
107
68
|
```bash
|
|
108
|
-
#
|
|
109
|
-
llm-usage
|
|
110
|
-
|
|
111
|
-
# Token trends for the last 7 days
|
|
112
|
-
llm-usage trends --metric tokens --days 7
|
|
69
|
+
# A chosen calendar range
|
|
70
|
+
llm-usage monthly --since 2026-06-01 --until 2026-06-30
|
|
113
71
|
|
|
114
|
-
#
|
|
115
|
-
llm-usage
|
|
116
|
-
```
|
|
72
|
+
# Current local month compared with the previous month
|
|
73
|
+
llm-usage compare
|
|
117
74
|
|
|
118
|
-
|
|
75
|
+
# Ten highest-cost conversations
|
|
76
|
+
llm-usage session --top 10
|
|
119
77
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
```bash
|
|
123
|
-
# Daily efficiency in current repository
|
|
124
|
-
llm-usage efficiency daily
|
|
78
|
+
# Usage grouped by repository
|
|
79
|
+
llm-usage session --by-repo
|
|
125
80
|
|
|
126
|
-
#
|
|
127
|
-
llm-usage
|
|
81
|
+
# Last 14 local days as a token series
|
|
82
|
+
llm-usage trends --metric tokens --days 14
|
|
128
83
|
|
|
129
|
-
#
|
|
130
|
-
llm-usage
|
|
84
|
+
# Candidate-model pricing against observed usage
|
|
85
|
+
llm-usage optimize monthly \
|
|
86
|
+
--provider openai \
|
|
87
|
+
--candidate-model gpt-4.1 \
|
|
88
|
+
--candidate-model gpt-5-codex
|
|
131
89
|
|
|
132
|
-
#
|
|
133
|
-
llm-usage
|
|
90
|
+
# Normalized events as JSONL, e.g. total tokens per line via jq
|
|
91
|
+
llm-usage events --since 2026-06-01 | jq '.totalTokens'
|
|
134
92
|
```
|
|
135
93
|
|
|
136
|
-
|
|
94
|
+
## Supported sources
|
|
137
95
|
|
|
138
|
-
|
|
96
|
+
| Source | Local format |
|
|
97
|
+
| ---------------------- | ------------- |
|
|
98
|
+
| pi | JSONL |
|
|
99
|
+
| codex | JSONL |
|
|
100
|
+
| Gemini CLI | JSON |
|
|
101
|
+
| Droid CLI | settings JSON |
|
|
102
|
+
| OpenCode | SQLite |
|
|
103
|
+
| OpenClaw | JSONL |
|
|
104
|
+
| Claude Code | JSONL |
|
|
105
|
+
| GitHub Copilot CLI | OTEL JSONL |
|
|
106
|
+
| Goose | SQLite |
|
|
107
|
+
| Amp | JSON |
|
|
108
|
+
| Qwen CLI | JSONL |
|
|
109
|
+
| Kimi CLI and Kimi Code | wire JSONL |
|
|
110
|
+
| Cline | task JSON |
|
|
111
|
+
| RooCode | task JSON |
|
|
112
|
+
| KiloCode | task JSON |
|
|
113
|
+
| Antigravity | SQLite |
|
|
139
114
|
|
|
140
|
-
-
|
|
141
|
-
- `Input`, `Output`, `Reasoning`, `Cache Read`, `Cache Write`, `Total`, and `Cost` come from repo-attributed usage events.
|
|
142
|
-
- `Tokens/Commit` uses `(Input + Output + Reasoning) / Commits` and excludes cache read/write tokens.
|
|
143
|
-
- `$/Commit` uses `Cost / Commits`.
|
|
144
|
-
- `$/1k Lines` uses `Cost / (ΔLines / 1000)`.
|
|
145
|
-
- `Commits/$` uses `Commits / Cost` (shown only when `Cost > 0`).
|
|
115
|
+
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.
|
|
146
116
|
|
|
147
|
-
|
|
148
|
-
When a denominator is zero, derived values in emitted rows render as `-`.
|
|
149
|
-
When pricing is incomplete, terminal/markdown output prefixes affected USD metrics with `~`.
|
|
117
|
+
SQLite-backed sources use the built-in `node:sqlite` module.
|
|
150
118
|
|
|
151
|
-
|
|
119
|
+
## Filters and configuration
|
|
152
120
|
|
|
153
121
|
```bash
|
|
154
|
-
|
|
155
|
-
llm-usage
|
|
156
|
-
llm-usage efficiency monthly --repo-dir /path/to/repo --source gemini
|
|
157
|
-
llm-usage efficiency monthly --repo-dir /path/to/repo --source droid
|
|
158
|
-
llm-usage efficiency monthly --repo-dir /path/to/repo --source opencode
|
|
159
|
-
llm-usage efficiency monthly --repo-dir /path/to/repo --source openclaw
|
|
160
|
-
llm-usage efficiency monthly --repo-dir /path/to/repo --source claude
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
Note: usage filters (`--source`, `--provider`, `--model`, `--pi-dir`, `--codex-dir`, `--gemini-dir`, `--droid-dir`, `--claude-dir`, `--opencode-db`, `--source-dir`) also constrain commit attribution: only commit days with matching repo-attributed usage events are counted.
|
|
164
|
-
|
|
165
|
-
### Optimize Reports
|
|
166
|
-
|
|
167
|
-
```bash
|
|
168
|
-
# Counterfactual pricing across candidate models
|
|
169
|
-
llm-usage optimize monthly --provider openai --candidate-model gpt-4.1 --candidate-model gpt-5-codex
|
|
170
|
-
|
|
171
|
-
# Keep only the cheapest candidate in JSON output
|
|
172
|
-
llm-usage optimize weekly --provider openai --candidate-model gpt-4.1,gpt-5-codex --top 1 --json
|
|
173
|
-
|
|
174
|
-
# Write a monthly share SVG
|
|
175
|
-
llm-usage optimize monthly --provider openai --candidate-model gpt-4.1 --candidate-model gpt-5-codex --share
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
`--provider` filters by billing entity. Provider aliases are normalized to billing roots (for example, `openai-codex` is treated as `openai`).
|
|
179
|
-
|
|
180
|
-
### Filtering
|
|
122
|
+
# Filter by source tool
|
|
123
|
+
llm-usage monthly --source codex,claude
|
|
181
124
|
|
|
182
|
-
|
|
183
|
-
# By source
|
|
184
|
-
llm-usage monthly --source pi,codex,gemini,droid,openclaw,claude
|
|
185
|
-
|
|
186
|
-
# By provider
|
|
125
|
+
# Filter by normalized billing provider
|
|
187
126
|
llm-usage monthly --provider openai
|
|
188
127
|
|
|
189
|
-
#
|
|
190
|
-
llm-usage monthly --model
|
|
191
|
-
|
|
192
|
-
# Combined filters
|
|
193
|
-
llm-usage monthly --source opencode --provider openai --model gpt-4.1
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
Use `--source` to scope where events came from (`pi`, `codex`, `gemini`, `droid`, `opencode`, `openclaw`, `claude`), and `--provider` to scope the billing entity behind those events.
|
|
128
|
+
# Filter by exact model or substring
|
|
129
|
+
llm-usage monthly --model codex
|
|
197
130
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
```bash
|
|
201
|
-
# Custom directories
|
|
202
|
-
llm-usage daily --source-dir pi=/path/to/pi --source-dir codex=/path/to/codex --source-dir gemini=/path/to/.gemini --source-dir droid=/path/to/.factory/sessions --source-dir openclaw=/path/to/.openclaw/agents --source-dir claude=/path/to/.claude/projects
|
|
203
|
-
|
|
204
|
-
# Explicit Gemini/Droid/Claude/OpenCode paths
|
|
205
|
-
llm-usage daily --gemini-dir /path/to/.gemini
|
|
206
|
-
llm-usage daily --droid-dir /path/to/.factory/sessions
|
|
207
|
-
llm-usage daily --claude-dir /path/to/.claude/projects
|
|
208
|
-
llm-usage daily --opencode-db /path/to/opencode.db
|
|
131
|
+
# Create a commented TOML config with editor schema support
|
|
132
|
+
llm-usage config init
|
|
209
133
|
```
|
|
210
134
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
```bash
|
|
214
|
-
# Use cached pricing only
|
|
215
|
-
llm-usage monthly --pricing-offline
|
|
216
|
-
|
|
217
|
-
# Continue even if pricing fetch fails
|
|
218
|
-
llm-usage monthly --ignore-pricing-failures
|
|
219
|
-
|
|
220
|
-
# Override per-model pricing from a local JSON file
|
|
221
|
-
llm-usage monthly --pricing-overrides ./pricing-overrides.json
|
|
222
|
-
```
|
|
135
|
+
`--source` identifies the tool that wrote an event. `--provider` identifies the billing entity behind its model. A Codex session can have `source=codex` and `provider=openai`.
|
|
223
136
|
|
|
224
|
-
|
|
137
|
+
The config precedence order is CLI flags, environment variables, TOML config, then built-in defaults. See [Configuration](https://ayagmar.github.io/llm-usage-metrics/configuration/) for every key and source path override.
|
|
225
138
|
|
|
226
|
-
|
|
139
|
+
## Pricing
|
|
227
140
|
|
|
228
|
-
|
|
229
|
-
- CPU: Intel Core Ultra 9 185H (22 logical CPUs)
|
|
230
|
-
- RAM: 62 GiB
|
|
231
|
-
- Storage: NVMe SSD
|
|
141
|
+
The CLI keeps a valid cost supplied by a source. When a source has no cost, it estimates one from LiteLLM pricing.
|
|
232
142
|
|
|
233
|
-
|
|
143
|
+
Pricing loads from a fresh cache, a network refresh, a stale cache, or the bundled snapshot. Use offline mode to skip the network request:
|
|
234
144
|
|
|
235
145
|
```bash
|
|
236
|
-
|
|
237
|
-
ccusage-codex monthly
|
|
238
|
-
llm-usage monthly --provider openai --source codex
|
|
239
|
-
|
|
240
|
-
# multi-source comparison for one provider (openai)
|
|
241
|
-
ccusage-codex monthly
|
|
242
|
-
llm-usage monthly --provider openai --source pi,codex,gemini,opencode
|
|
146
|
+
llm-usage monthly --pricing-offline
|
|
243
147
|
```
|
|
244
148
|
|
|
245
|
-
|
|
149
|
+
Cost rendering makes incomplete data visible:
|
|
246
150
|
|
|
247
|
-
|
|
151
|
+
- `$12.34` means the full row has resolved cost.
|
|
152
|
+
- `~$12.34` means the known cost is partial.
|
|
153
|
+
- `-` means no contributing event has a resolved cost.
|
|
248
154
|
|
|
249
|
-
|
|
250
|
-
| ---------------------------------------------------------------------- | ---------- | ---------: | -------: |
|
|
251
|
-
| `ccusage-codex monthly` | no cache | 16.785 | 17.288 |
|
|
252
|
-
| `ccusage-codex monthly --offline` | with cache | 16.995 | 17.594 |
|
|
253
|
-
| `llm-usage monthly --provider openai --source codex` | no cache | 3.651 | 3.760 |
|
|
254
|
-
| `llm-usage monthly --provider openai --source codex --pricing-offline` | with cache | 0.746 | 0.724 |
|
|
155
|
+
The pricing request never includes session content. See [Pricing](https://ayagmar.github.io/llm-usage-metrics/pricing/) for rate matching, overrides, and error behavior.
|
|
255
156
|
|
|
256
|
-
|
|
157
|
+
## Local event ledger
|
|
257
158
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
| Tool | Cache mode | Median (s) | Mean (s) |
|
|
261
|
-
| ----------------------------------------------------------------------------------------- | ---------- | ---------: | -------: |
|
|
262
|
-
| `ccusage-codex monthly` | no cache | 17.297 | 17.463 |
|
|
263
|
-
| `ccusage-codex monthly --offline` | with cache | 16.698 | 16.745 |
|
|
264
|
-
| `llm-usage monthly --provider openai --source pi,codex,gemini,opencode` | no cache | 4.767 | 4.864 |
|
|
265
|
-
| `llm-usage monthly --provider openai --source pi,codex,gemini,opencode --pricing-offline` | with cache | 0.941 | 0.951 |
|
|
266
|
-
|
|
267
|
-
Speedups (median): `3.63x` faster cold, `17.75x` faster cached.
|
|
268
|
-
|
|
269
|
-
Full methodology, cache-mode definition, and scope caveats are documented in the Astro docs: [Benchmarks](https://ayagmar.github.io/llm-usage-metrics/benchmarks/).
|
|
270
|
-
|
|
271
|
-
Re-run direct parity benchmark locally:
|
|
159
|
+
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:
|
|
272
160
|
|
|
273
161
|
```bash
|
|
274
|
-
|
|
162
|
+
llm-usage monthly --history
|
|
275
163
|
```
|
|
276
164
|
|
|
277
|
-
|
|
165
|
+
`prune` is a dry run unless you pass `--apply`:
|
|
278
166
|
|
|
279
167
|
```bash
|
|
280
|
-
|
|
168
|
+
llm-usage prune --suppressed
|
|
169
|
+
llm-usage prune --departed-before 2026-01-01 --apply
|
|
281
170
|
```
|
|
282
171
|
|
|
283
|
-
|
|
172
|
+
Deleting the ledger also deletes retained history. Read [Caching](https://ayagmar.github.io/llm-usage-metrics/caching/) before clearing it as a troubleshooting step.
|
|
173
|
+
|
|
174
|
+
## Output
|
|
284
175
|
|
|
285
176
|
```bash
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
--json-output ./tmp/production-benchmark-openai-codex.json \
|
|
290
|
-
--markdown-output ./tmp/production-benchmark-openai-codex.md
|
|
291
|
-
|
|
292
|
-
pnpm run perf:production-benchmark -- \
|
|
293
|
-
--runs 5 \
|
|
294
|
-
--llm-source pi,codex,gemini,opencode \
|
|
295
|
-
--json-output ./tmp/production-benchmark-openai-multi-source.json \
|
|
296
|
-
--markdown-output ./tmp/production-benchmark-openai-multi-source.md
|
|
177
|
+
llm-usage daily --json
|
|
178
|
+
llm-usage daily --markdown
|
|
179
|
+
llm-usage monthly --share
|
|
297
180
|
```
|
|
298
181
|
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
### Environment Variables
|
|
302
|
-
|
|
303
|
-
| Variable | Description |
|
|
304
|
-
| -------------------------------- | ---------------------------------- |
|
|
305
|
-
| `LLM_USAGE_SKIP_UPDATE_CHECK` | Skip update check (`1`) |
|
|
306
|
-
| `LLM_USAGE_UPDATE_CACHE_SCOPE` | Update cache scope |
|
|
307
|
-
| `LLM_USAGE_PRICING_CACHE_TTL_MS` | Pricing cache duration |
|
|
308
|
-
| `LLM_USAGE_PARSE_MAX_PARALLEL` | Max parallel file parses (`1-64`) |
|
|
309
|
-
| `LLM_USAGE_PARSE_CACHE_ENABLED` | Enable parse cache (`1/0`) |
|
|
310
|
-
| `LLM_USAGE_PROFILE_RUNTIME` | Emit runtime profiling diagnostics |
|
|
182
|
+
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/).
|
|
311
183
|
|
|
312
|
-
|
|
184
|
+
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.
|
|
313
185
|
|
|
314
|
-
|
|
186
|
+
## Performance
|
|
315
187
|
|
|
316
|
-
|
|
188
|
+
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.
|
|
317
189
|
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
- 1-hour cache TTL
|
|
321
|
-
- Fresh cached update results are used immediately without any network call
|
|
322
|
-
- Stale or missing cache triggers a bounded fetch (default 1s timeout) so the update prompt stays consistent across commands, instead of silently skipping the run that refreshes the cache
|
|
323
|
-
- Skipped for `--help`, `--version`, `npx`, and direct source/development runs
|
|
324
|
-
- Prompts only in interactive TTY sessions
|
|
325
|
-
|
|
326
|
-
Disable with:
|
|
327
|
-
|
|
328
|
-
```bash
|
|
329
|
-
LLM_USAGE_SKIP_UPDATE_CHECK=1 llm-usage daily
|
|
330
|
-
```
|
|
190
|
+
Read and reproduce the [benchmark](https://ayagmar.github.io/llm-usage-metrics/benchmarks/) before applying its results to another workload.
|
|
331
191
|
|
|
332
|
-
##
|
|
192
|
+
## Development
|
|
333
193
|
|
|
334
194
|
```bash
|
|
335
|
-
# Install dependencies
|
|
336
195
|
pnpm install
|
|
337
|
-
|
|
338
|
-
# Run quality checks
|
|
339
196
|
pnpm run lint
|
|
340
197
|
pnpm run typecheck
|
|
341
198
|
pnpm run test
|
|
342
199
|
pnpm run format:check
|
|
343
|
-
|
|
344
|
-
# Build
|
|
345
200
|
pnpm run build
|
|
346
|
-
|
|
347
|
-
# Run locally
|
|
348
|
-
pnpm cli daily
|
|
349
201
|
```
|
|
350
202
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
- **[Getting Started](https://ayagmar.github.io/llm-usage-metrics/getting-started/)** — Installation and first steps
|
|
354
|
-
- **[CLI Reference](https://ayagmar.github.io/llm-usage-metrics/cli-reference/)** — Complete command reference
|
|
355
|
-
- **[Efficiency](https://ayagmar.github.io/llm-usage-metrics/efficiency/)** — Efficiency report semantics and interpretation
|
|
356
|
-
- **[Optimize](https://ayagmar.github.io/llm-usage-metrics/optimize/)** — Counterfactual candidate-model pricing semantics
|
|
357
|
-
- **[Data Sources](https://ayagmar.github.io/llm-usage-metrics/sources/)** — Source configuration
|
|
358
|
-
- **[Configuration](https://ayagmar.github.io/llm-usage-metrics/configuration/)** — Environment variables
|
|
359
|
-
- **[Security](https://ayagmar.github.io/llm-usage-metrics/security/)** — Current security controls, dependency hygiene, and contributor steps
|
|
360
|
-
- **[Benchmarks](https://ayagmar.github.io/llm-usage-metrics/benchmarks/)** — Production benchmark methodology and results
|
|
361
|
-
- **[Architecture](https://ayagmar.github.io/llm-usage-metrics/architecture/)** — Technical overview
|
|
362
|
-
|
|
363
|
-
## 🔐 Security
|
|
203
|
+
Site commands:
|
|
364
204
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
|
|
205
|
+
```bash
|
|
206
|
+
pnpm run site:check
|
|
207
|
+
pnpm run site:build
|
|
208
|
+
pnpm run site:dev
|
|
209
|
+
```
|
|
371
210
|
|
|
372
|
-
|
|
211
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) and [docs/development.md](./docs/development.md) for the contributor workflow.
|
|
373
212
|
|
|
374
|
-
##
|
|
213
|
+
## License
|
|
375
214
|
|
|
376
|
-
MIT
|
|
215
|
+
[MIT](./LICENSE)
|