clockwork-cli 0.2.1__tar.gz → 0.4.0__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: clockwork-cli
3
- Version: 0.2.1
3
+ Version: 0.4.0
4
4
  Summary: Mine your Claude Code and Codex session logs to estimate active time
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://github.com/danielsich/clockwork
@@ -54,12 +54,32 @@ DATE ACTIVE TIME PROMPTS BAR
54
54
  ## How it works
55
55
 
56
56
  `clockwork` reads the JSONL transcripts each tool writes, extracts the
57
- timestamps of your **prompts** (not the assistant's replies), and groups them
57
+ timestamps of user-side activity (not the assistant's replies), and groups them
58
58
  into sessions. Any gap longer than the *idle threshold* (default 30 minutes)
59
59
  starts a new session. A session's duration is the time from its first to its
60
- last prompt, split across calendar-day boundaries so a session that crosses
60
+ last record, split across calendar-day boundaries so a session that crosses
61
61
  midnight is credited to each day it spans.
62
62
 
63
+ **Prompts vs. activity.** On Claude, most user-side records aren't things you
64
+ typed: the API sends every tool result back to the model as a user message.
65
+ Those records still count as *activity*, because they show Claude working
66
+ through a long tool run, so sessions and active time are built on all of them.
67
+ The **Prompts** column counts only messages a person sent. Claude Code tags
68
+ these with `origin.kind: "human"` in newer logs; older records are classified by
69
+ shape, so tool results, slash-command output, `!` shell output, meta records,
70
+ task notifications, and interrupt markers are left out. Text typed while a tool
71
+ was running is counted. Codex follows the same rule: its activity is your
72
+ prompts plus every tool result (`function_call_output`,
73
+ `custom_tool_call_output`), and its Prompts column is your prompts only.
74
+
75
+ In JSON output, `prompts` is the activity count (every user-side record, tool
76
+ results included) on both providers, so Claude consumers see the meaning they
77
+ always had, and `human_prompts` carries the corrected count. On Codex,
78
+ `prompts` used to count prompts only and now includes tool results too; read
79
+ `human_prompts` for the number of messages you sent. Claude Code's Insights report counts more broadly than `human_prompts`
80
+ does (it includes slash commands, shell output, and interrupts), so expect
81
+ Insights' "messages" to run higher.
82
+
63
83
  **Data sources**
64
84
 
65
85
  | Provider | Location |
@@ -74,11 +94,11 @@ midnight is credited to each day it spans.
74
94
  > reasonable estimate, not a stopwatch.
75
95
 
76
96
  > **`both` and path matching:** `both` combines Claude and Codex prompts by
77
- > project path. Single-project mode (`clockwork both ~/dev/x`) is exact,
78
- > because it encodes the path you pass. In `all` / `export` / `list`, projects
79
- > are matched by their displayed path — and Claude stores paths dash-encoded,
80
- > so one containing spaces or dashes can't always be reversed to match Codex's
81
- > real path. Such a project may appear as two rows rather than merging.
97
+ > project path. Claude's folder names are lossy (every character that isn't a
98
+ > letter or digit becomes `-`), so clockwork labels each Claude project with
99
+ > the real `cwd` recorded in its logs, which then lines up with Codex's path.
100
+ > Only a folder whose logs carry no matching `cwd` falls back to a decoded
101
+ > guess, and that guess may appear as a separate row rather than merging.
82
102
 
83
103
  ## Requirements
84
104
 
@@ -141,6 +161,7 @@ Options:
141
161
  form like 7d (7 days ago) or 2w (2 weeks ago)
142
162
  --detail <level> export granularity: raw | sessions | daily (default raw)
143
163
  --anonymize export: replace project paths with a hash id + generic name
164
+ --tokens Also report token usage and a per-model breakdown
144
165
  ```
145
166
 
146
167
  ### Examples
@@ -174,6 +195,10 @@ clockwork claude all --since 7d
174
195
  # A specific date range for one project
175
196
  clockwork claude ~/dev/myproject --since 2026-07-01 --until 2026-07-05
176
197
 
198
+ # Token and model usage, alongside the timings
199
+ clockwork claude all --tokens
200
+ clockwork both today --tokens
201
+
177
202
  # Machine-readable output — pipe into jq, a spreadsheet, or a dashboard
178
203
  clockwork codex all --json | jq '.projects[] | {project, minutes}'
179
204
  ```
@@ -206,6 +231,60 @@ usage still go to stderr), so clockwork composes with `jq`, cron jobs, or any
206
231
  dashboard. Exit codes are script-friendly: `0` on success, `1` when nothing
207
232
  matched, `2` for bad arguments.
208
233
 
234
+ ### Token & model usage (`--tokens`)
235
+
236
+ `--tokens` adds token counts and a per-model breakdown to any command. It reads
237
+ the usage each tool already records next to your prompts — nothing is estimated,
238
+ and no API is called.
239
+
240
+ ```
241
+ Tokens : 760.7M across 6,739 responses
242
+ In/Out : 1.6M in · 5.7M out
243
+ Cache : 731.7M read · 21.7M write
244
+ ========================================================================================
245
+
246
+ PROJECT TIME PROMPTS IN OUT CACHE TOTAL
247
+ ----------------------------------------------------------------------------------------
248
+ /Users/you/dev/alpha 54h 08m 3693 1.1M 2.8M 394.8M 398.7M
249
+ /Users/you/dev/beta 19h 01m 1414 196.4k 870.7k 121.5M 122.6M
250
+
251
+ MODEL RESP INPUT OUTPUT CACHE R CACHE W TOTAL
252
+ --------------------------------------------------------------------------------
253
+ claude-opus-4-8 4,732 1.4M 4.3M 572.0M 15.9M 593.7M
254
+ claude-sonnet-4-6 1,431 10.2k 786.0k 108.8M 2.8M 111.6M
255
+ ```
256
+
257
+ **The counts are normalized across the two tools**, because they don't report
258
+ the same way:
259
+
260
+ | field | meaning | claude | codex |
261
+ | ------------- | ------------------------------ | ------ | ----- |
262
+ | `input` | fresh (uncached) input tokens | as reported | `input_tokens` minus `cached_input_tokens`, which Codex nests inside it |
263
+ | `output` | output tokens | includes thinking | includes reasoning |
264
+ | `cache_read` | input served from cache | `cache_read_input_tokens` | `cached_input_tokens` |
265
+ | `cache_write` | input written to cache | `cache_creation_input_tokens` | never reported (always 0) |
266
+ | `reasoning` | thinking tokens, a *subset* of `output` | not broken out (always 0) | `reasoning_output_tokens` |
267
+
268
+ `total` is `input + output + cache_read + cache_write`; `reasoning` is
269
+ deliberately left out of it, since `output` already covers those tokens.
270
+
271
+ Two counting traps are handled for you, both of which inflate the numbers if
272
+ you read the logs naively:
273
+
274
+ - **Claude** writes one line per content block — thinking, text, and each tool
275
+ call — and every line of a single API response repeats its usage block.
276
+ Counting per line overstates usage roughly 2.6x, so responses are
277
+ deduplicated on their message id. Subagent transcripts
278
+ (`<session>/subagents/*.jsonl`) are read too; there the first line of a
279
+ response holds a streaming partial, so the largest count per field wins.
280
+ - **Codex** re-emits a stale `last_token_usage` on aborted and no-op turns that
281
+ its cumulative counter never absorbs, so a turn's real cost is read as the
282
+ rise in `total_token_usage` instead. The model name comes from the preceding
283
+ `turn_context` record (`session_meta` only names the provider).
284
+
285
+ What it can't tell you is cost — the logs carry no prices, and subscription
286
+ usage isn't billed per token anyway.
287
+
209
288
  ## Exporting for external tools
210
289
 
211
290
  `clockwork <provider> export` writes a single **self-describing, versioned**
@@ -258,17 +337,18 @@ for a combined view, so nothing is lost either way.
258
337
  - `totals.by_provider` breaks the grand totals down per provider; the grand
259
338
  `totals` stay the cross-provider sum.
260
339
 
261
- ### Export schema (`clockwork/v2`)
340
+ ### Export schema (`clockwork/v3`)
262
341
 
263
342
  ```jsonc
264
343
  {
265
- "schema": "clockwork/v2",
344
+ "schema": "clockwork/v3",
266
345
  "generated_at": "2026-07-06T00:30:00+02:00", // local ISO-8601
267
346
  "provider": "both", // "claude" | "codex" | "both"
268
347
  "providers": ["claude", "codex"], // sorted, distinct; ≥ 1 element
269
348
  "idle_threshold_min": 30,
270
349
  "detail": "raw", // raw | sessions | daily
271
350
  "anonymized": false,
351
+ "tokens": false, // true when --tokens was given (adds the fields below)
272
352
  "daily_tz": "UTC", // the "daily" buckets use UTC calendar dates
273
353
  "since": null, // ISO bound if --since was given, else null
274
354
  "until": null,
@@ -279,30 +359,65 @@ for a combined view, so nothing is lost either way.
279
359
  "name": "myproject", // basename, or "project-N" when anonymized
280
360
  "path": "/Users/you/dev/myproject", // omitted when anonymized
281
361
  "totals": {
282
- "minutes": 1234.76, "prompts": 1646, "sessions": 27,
362
+ "minutes": 1234.76,
363
+ "prompts": 1646, // every user-side record, tool results included
364
+ "human_prompts": 231, // messages a person sent
365
+ "sessions": 27,
283
366
  "active_days": 12,
284
367
  "first": 1780521570, "last": 1782130426 // epoch seconds
285
368
  },
286
- "daily": [ { "date": "2026-06-03", "minutes": 4.34, "prompts": 27 } ],
369
+ "daily": [ { "date": "2026-06-03", "minutes": 4.34, "prompts": 27,
370
+ "human_prompts": 4 } ],
371
+ // every "tokens" block below appears only with --tokens
372
+ "tokens": {
373
+ "responses": 373, // API responses, deduplicated
374
+ "input": 31065, "output": 287747,
375
+ "cache_read": 20753836, "cache_write": 579725,
376
+ "reasoning": 0, // subset of output; Codex only
377
+ "total": 21652373, // input + output + cache_read + cache_write
378
+ "by_model": [ // biggest consumer first
379
+ { "model": "claude-opus-4-8", "responses": 238, "input": 30046,
380
+ "output": 177141, "cache_read": 13207329, "cache_write": 352749,
381
+ "reasoning": 0, "total": 13767265 }
382
+ ]
383
+ },
287
384
  "sessions": [ { "start": 1780521570, "end": 1780521830,
288
- "minutes": 4.34, "prompts": 27 } ], // detail >= sessions
289
- "prompts": [ 1780521570, 1780521582 ] // detail == raw
385
+ "minutes": 4.34, "prompts": 27,
386
+ "human_prompts": 4 } ], // detail >= sessions
387
+ "prompts": [ 1780521570, 1780521582 ], // detail == raw
388
+ "human_prompts": [ 1780521570 ] // detail == raw
290
389
  }
291
390
  ],
292
391
  "totals": {
293
- "projects": 6, "minutes": 3392.97, "prompts": 4588, "sessions": 64,
392
+ "projects": 6, "minutes": 3392.97, "prompts": 4588, "human_prompts": 950,
393
+ "sessions": 64,
394
+ "tokens": { /* same shape, summed across every project */ },
294
395
  "by_provider": {
295
- "claude": { "projects": 4, "minutes": 2500.0, "prompts": 3000, "sessions": 40 },
296
- "codex": { "projects": 2, "minutes": 892.97, "prompts": 1588, "sessions": 24 }
396
+ "claude": { "projects": 4, "minutes": 2500.0, "prompts": 3000,
397
+ "human_prompts": 420, "sessions": 40, "tokens": { /* ... */ } },
398
+ "codex": { "projects": 2, "minutes": 892.97, "prompts": 1588,
399
+ "human_prompts": 530, "sessions": 24, "tokens": { /* ... */ } }
297
400
  }
298
401
  }
299
402
  }
300
403
  ```
301
404
 
405
+ `human_prompts` sits beside every `prompts` field. It was added inside
406
+ `clockwork/v3` without a version bump, because nothing existing changed
407
+ meaning: a consumer that doesn't know the field reads the bundle as before. If
408
+ you display a prompt count, read `human_prompts` when it's present and fall
409
+ back to `prompts` for older bundles.
410
+
302
411
  All instants are **UTC-based epoch seconds** (`new Date(sec * 1000)` in JS), so
303
412
  the consumer picks the display timezone. The `schema` field is the version
304
- contract — `clockwork/v2` is a breaking bump over `v1` (provider moved to the
305
- project level), so tools should guard on it.
413
+ contract — `clockwork/v2` was a breaking bump over `v1` (provider moved to the
414
+ project level), so tools should guard on it. `clockwork/v3` is **additive
415
+ only**: it adds the `tokens` flag and the `tokens` blocks described above, and a
416
+ v2 consumer reads a v3 bundle unchanged.
417
+
418
+ The per-day `tokens` buckets sum to the project's `tokens`, project totals sum
419
+ to `totals.by_provider`, and those sum to `totals.tokens` — at every level, and
420
+ per model.
306
421
 
307
422
  ## License
308
423
 
@@ -36,12 +36,32 @@ DATE ACTIVE TIME PROMPTS BAR
36
36
  ## How it works
37
37
 
38
38
  `clockwork` reads the JSONL transcripts each tool writes, extracts the
39
- timestamps of your **prompts** (not the assistant's replies), and groups them
39
+ timestamps of user-side activity (not the assistant's replies), and groups them
40
40
  into sessions. Any gap longer than the *idle threshold* (default 30 minutes)
41
41
  starts a new session. A session's duration is the time from its first to its
42
- last prompt, split across calendar-day boundaries so a session that crosses
42
+ last record, split across calendar-day boundaries so a session that crosses
43
43
  midnight is credited to each day it spans.
44
44
 
45
+ **Prompts vs. activity.** On Claude, most user-side records aren't things you
46
+ typed: the API sends every tool result back to the model as a user message.
47
+ Those records still count as *activity*, because they show Claude working
48
+ through a long tool run, so sessions and active time are built on all of them.
49
+ The **Prompts** column counts only messages a person sent. Claude Code tags
50
+ these with `origin.kind: "human"` in newer logs; older records are classified by
51
+ shape, so tool results, slash-command output, `!` shell output, meta records,
52
+ task notifications, and interrupt markers are left out. Text typed while a tool
53
+ was running is counted. Codex follows the same rule: its activity is your
54
+ prompts plus every tool result (`function_call_output`,
55
+ `custom_tool_call_output`), and its Prompts column is your prompts only.
56
+
57
+ In JSON output, `prompts` is the activity count (every user-side record, tool
58
+ results included) on both providers, so Claude consumers see the meaning they
59
+ always had, and `human_prompts` carries the corrected count. On Codex,
60
+ `prompts` used to count prompts only and now includes tool results too; read
61
+ `human_prompts` for the number of messages you sent. Claude Code's Insights report counts more broadly than `human_prompts`
62
+ does (it includes slash commands, shell output, and interrupts), so expect
63
+ Insights' "messages" to run higher.
64
+
45
65
  **Data sources**
46
66
 
47
67
  | Provider | Location |
@@ -56,11 +76,11 @@ midnight is credited to each day it spans.
56
76
  > reasonable estimate, not a stopwatch.
57
77
 
58
78
  > **`both` and path matching:** `both` combines Claude and Codex prompts by
59
- > project path. Single-project mode (`clockwork both ~/dev/x`) is exact,
60
- > because it encodes the path you pass. In `all` / `export` / `list`, projects
61
- > are matched by their displayed path — and Claude stores paths dash-encoded,
62
- > so one containing spaces or dashes can't always be reversed to match Codex's
63
- > real path. Such a project may appear as two rows rather than merging.
79
+ > project path. Claude's folder names are lossy (every character that isn't a
80
+ > letter or digit becomes `-`), so clockwork labels each Claude project with
81
+ > the real `cwd` recorded in its logs, which then lines up with Codex's path.
82
+ > Only a folder whose logs carry no matching `cwd` falls back to a decoded
83
+ > guess, and that guess may appear as a separate row rather than merging.
64
84
 
65
85
  ## Requirements
66
86
 
@@ -123,6 +143,7 @@ Options:
123
143
  form like 7d (7 days ago) or 2w (2 weeks ago)
124
144
  --detail <level> export granularity: raw | sessions | daily (default raw)
125
145
  --anonymize export: replace project paths with a hash id + generic name
146
+ --tokens Also report token usage and a per-model breakdown
126
147
  ```
127
148
 
128
149
  ### Examples
@@ -156,6 +177,10 @@ clockwork claude all --since 7d
156
177
  # A specific date range for one project
157
178
  clockwork claude ~/dev/myproject --since 2026-07-01 --until 2026-07-05
158
179
 
180
+ # Token and model usage, alongside the timings
181
+ clockwork claude all --tokens
182
+ clockwork both today --tokens
183
+
159
184
  # Machine-readable output — pipe into jq, a spreadsheet, or a dashboard
160
185
  clockwork codex all --json | jq '.projects[] | {project, minutes}'
161
186
  ```
@@ -188,6 +213,60 @@ usage still go to stderr), so clockwork composes with `jq`, cron jobs, or any
188
213
  dashboard. Exit codes are script-friendly: `0` on success, `1` when nothing
189
214
  matched, `2` for bad arguments.
190
215
 
216
+ ### Token & model usage (`--tokens`)
217
+
218
+ `--tokens` adds token counts and a per-model breakdown to any command. It reads
219
+ the usage each tool already records next to your prompts — nothing is estimated,
220
+ and no API is called.
221
+
222
+ ```
223
+ Tokens : 760.7M across 6,739 responses
224
+ In/Out : 1.6M in · 5.7M out
225
+ Cache : 731.7M read · 21.7M write
226
+ ========================================================================================
227
+
228
+ PROJECT TIME PROMPTS IN OUT CACHE TOTAL
229
+ ----------------------------------------------------------------------------------------
230
+ /Users/you/dev/alpha 54h 08m 3693 1.1M 2.8M 394.8M 398.7M
231
+ /Users/you/dev/beta 19h 01m 1414 196.4k 870.7k 121.5M 122.6M
232
+
233
+ MODEL RESP INPUT OUTPUT CACHE R CACHE W TOTAL
234
+ --------------------------------------------------------------------------------
235
+ claude-opus-4-8 4,732 1.4M 4.3M 572.0M 15.9M 593.7M
236
+ claude-sonnet-4-6 1,431 10.2k 786.0k 108.8M 2.8M 111.6M
237
+ ```
238
+
239
+ **The counts are normalized across the two tools**, because they don't report
240
+ the same way:
241
+
242
+ | field | meaning | claude | codex |
243
+ | ------------- | ------------------------------ | ------ | ----- |
244
+ | `input` | fresh (uncached) input tokens | as reported | `input_tokens` minus `cached_input_tokens`, which Codex nests inside it |
245
+ | `output` | output tokens | includes thinking | includes reasoning |
246
+ | `cache_read` | input served from cache | `cache_read_input_tokens` | `cached_input_tokens` |
247
+ | `cache_write` | input written to cache | `cache_creation_input_tokens` | never reported (always 0) |
248
+ | `reasoning` | thinking tokens, a *subset* of `output` | not broken out (always 0) | `reasoning_output_tokens` |
249
+
250
+ `total` is `input + output + cache_read + cache_write`; `reasoning` is
251
+ deliberately left out of it, since `output` already covers those tokens.
252
+
253
+ Two counting traps are handled for you, both of which inflate the numbers if
254
+ you read the logs naively:
255
+
256
+ - **Claude** writes one line per content block — thinking, text, and each tool
257
+ call — and every line of a single API response repeats its usage block.
258
+ Counting per line overstates usage roughly 2.6x, so responses are
259
+ deduplicated on their message id. Subagent transcripts
260
+ (`<session>/subagents/*.jsonl`) are read too; there the first line of a
261
+ response holds a streaming partial, so the largest count per field wins.
262
+ - **Codex** re-emits a stale `last_token_usage` on aborted and no-op turns that
263
+ its cumulative counter never absorbs, so a turn's real cost is read as the
264
+ rise in `total_token_usage` instead. The model name comes from the preceding
265
+ `turn_context` record (`session_meta` only names the provider).
266
+
267
+ What it can't tell you is cost — the logs carry no prices, and subscription
268
+ usage isn't billed per token anyway.
269
+
191
270
  ## Exporting for external tools
192
271
 
193
272
  `clockwork <provider> export` writes a single **self-describing, versioned**
@@ -240,17 +319,18 @@ for a combined view, so nothing is lost either way.
240
319
  - `totals.by_provider` breaks the grand totals down per provider; the grand
241
320
  `totals` stay the cross-provider sum.
242
321
 
243
- ### Export schema (`clockwork/v2`)
322
+ ### Export schema (`clockwork/v3`)
244
323
 
245
324
  ```jsonc
246
325
  {
247
- "schema": "clockwork/v2",
326
+ "schema": "clockwork/v3",
248
327
  "generated_at": "2026-07-06T00:30:00+02:00", // local ISO-8601
249
328
  "provider": "both", // "claude" | "codex" | "both"
250
329
  "providers": ["claude", "codex"], // sorted, distinct; ≥ 1 element
251
330
  "idle_threshold_min": 30,
252
331
  "detail": "raw", // raw | sessions | daily
253
332
  "anonymized": false,
333
+ "tokens": false, // true when --tokens was given (adds the fields below)
254
334
  "daily_tz": "UTC", // the "daily" buckets use UTC calendar dates
255
335
  "since": null, // ISO bound if --since was given, else null
256
336
  "until": null,
@@ -261,30 +341,65 @@ for a combined view, so nothing is lost either way.
261
341
  "name": "myproject", // basename, or "project-N" when anonymized
262
342
  "path": "/Users/you/dev/myproject", // omitted when anonymized
263
343
  "totals": {
264
- "minutes": 1234.76, "prompts": 1646, "sessions": 27,
344
+ "minutes": 1234.76,
345
+ "prompts": 1646, // every user-side record, tool results included
346
+ "human_prompts": 231, // messages a person sent
347
+ "sessions": 27,
265
348
  "active_days": 12,
266
349
  "first": 1780521570, "last": 1782130426 // epoch seconds
267
350
  },
268
- "daily": [ { "date": "2026-06-03", "minutes": 4.34, "prompts": 27 } ],
351
+ "daily": [ { "date": "2026-06-03", "minutes": 4.34, "prompts": 27,
352
+ "human_prompts": 4 } ],
353
+ // every "tokens" block below appears only with --tokens
354
+ "tokens": {
355
+ "responses": 373, // API responses, deduplicated
356
+ "input": 31065, "output": 287747,
357
+ "cache_read": 20753836, "cache_write": 579725,
358
+ "reasoning": 0, // subset of output; Codex only
359
+ "total": 21652373, // input + output + cache_read + cache_write
360
+ "by_model": [ // biggest consumer first
361
+ { "model": "claude-opus-4-8", "responses": 238, "input": 30046,
362
+ "output": 177141, "cache_read": 13207329, "cache_write": 352749,
363
+ "reasoning": 0, "total": 13767265 }
364
+ ]
365
+ },
269
366
  "sessions": [ { "start": 1780521570, "end": 1780521830,
270
- "minutes": 4.34, "prompts": 27 } ], // detail >= sessions
271
- "prompts": [ 1780521570, 1780521582 ] // detail == raw
367
+ "minutes": 4.34, "prompts": 27,
368
+ "human_prompts": 4 } ], // detail >= sessions
369
+ "prompts": [ 1780521570, 1780521582 ], // detail == raw
370
+ "human_prompts": [ 1780521570 ] // detail == raw
272
371
  }
273
372
  ],
274
373
  "totals": {
275
- "projects": 6, "minutes": 3392.97, "prompts": 4588, "sessions": 64,
374
+ "projects": 6, "minutes": 3392.97, "prompts": 4588, "human_prompts": 950,
375
+ "sessions": 64,
376
+ "tokens": { /* same shape, summed across every project */ },
276
377
  "by_provider": {
277
- "claude": { "projects": 4, "minutes": 2500.0, "prompts": 3000, "sessions": 40 },
278
- "codex": { "projects": 2, "minutes": 892.97, "prompts": 1588, "sessions": 24 }
378
+ "claude": { "projects": 4, "minutes": 2500.0, "prompts": 3000,
379
+ "human_prompts": 420, "sessions": 40, "tokens": { /* ... */ } },
380
+ "codex": { "projects": 2, "minutes": 892.97, "prompts": 1588,
381
+ "human_prompts": 530, "sessions": 24, "tokens": { /* ... */ } }
279
382
  }
280
383
  }
281
384
  }
282
385
  ```
283
386
 
387
+ `human_prompts` sits beside every `prompts` field. It was added inside
388
+ `clockwork/v3` without a version bump, because nothing existing changed
389
+ meaning: a consumer that doesn't know the field reads the bundle as before. If
390
+ you display a prompt count, read `human_prompts` when it's present and fall
391
+ back to `prompts` for older bundles.
392
+
284
393
  All instants are **UTC-based epoch seconds** (`new Date(sec * 1000)` in JS), so
285
394
  the consumer picks the display timezone. The `schema` field is the version
286
- contract — `clockwork/v2` is a breaking bump over `v1` (provider moved to the
287
- project level), so tools should guard on it.
395
+ contract — `clockwork/v2` was a breaking bump over `v1` (provider moved to the
396
+ project level), so tools should guard on it. `clockwork/v3` is **additive
397
+ only**: it adds the `tokens` flag and the `tokens` blocks described above, and a
398
+ v2 consumer reads a v3 bundle unchanged.
399
+
400
+ The per-day `tokens` buckets sum to the project's `tokens`, project totals sum
401
+ to `totals.by_provider`, and those sum to `totals.tokens` — at every level, and
402
+ per model.
288
403
 
289
404
  ## License
290
405
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "clockwork-cli"
7
- version = "0.2.1"
7
+ version = "0.4.0"
8
8
  description = "Mine your Claude Code and Codex session logs to estimate active time"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -28,3 +28,7 @@ clockwork = "clockwork_cli:main"
28
28
 
29
29
  [tool.setuptools.packages.find]
30
30
  where = ["src"]
31
+
32
+ [tool.pytest.ini_options]
33
+ # Test the working tree, not whatever copy happens to be pip-installed.
34
+ pythonpath = ["src"]