clockwork-cli 0.2.0__tar.gz → 0.3.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.0
3
+ Version: 0.3.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
@@ -141,6 +141,7 @@ Options:
141
141
  form like 7d (7 days ago) or 2w (2 weeks ago)
142
142
  --detail <level> export granularity: raw | sessions | daily (default raw)
143
143
  --anonymize export: replace project paths with a hash id + generic name
144
+ --tokens Also report token usage and a per-model breakdown
144
145
  ```
145
146
 
146
147
  ### Examples
@@ -174,6 +175,10 @@ clockwork claude all --since 7d
174
175
  # A specific date range for one project
175
176
  clockwork claude ~/dev/myproject --since 2026-07-01 --until 2026-07-05
176
177
 
178
+ # Token and model usage, alongside the timings
179
+ clockwork claude all --tokens
180
+ clockwork both today --tokens
181
+
177
182
  # Machine-readable output — pipe into jq, a spreadsheet, or a dashboard
178
183
  clockwork codex all --json | jq '.projects[] | {project, minutes}'
179
184
  ```
@@ -206,6 +211,58 @@ usage still go to stderr), so clockwork composes with `jq`, cron jobs, or any
206
211
  dashboard. Exit codes are script-friendly: `0` on success, `1` when nothing
207
212
  matched, `2` for bad arguments.
208
213
 
214
+ ### Token & model usage (`--tokens`)
215
+
216
+ `--tokens` adds token counts and a per-model breakdown to any command. It reads
217
+ the usage each tool already records next to your prompts — nothing is estimated,
218
+ and no API is called.
219
+
220
+ ```
221
+ Tokens : 760.7M across 6,739 responses
222
+ In/Out : 1.6M in · 5.7M out
223
+ Cache : 731.7M read · 21.7M write
224
+ ========================================================================================
225
+
226
+ PROJECT TIME PROMPTS IN OUT CACHE TOTAL
227
+ ----------------------------------------------------------------------------------------
228
+ /Users/you/dev/alpha 54h 08m 3693 1.1M 2.8M 394.8M 398.7M
229
+ /Users/you/dev/beta 19h 01m 1414 196.4k 870.7k 121.5M 122.6M
230
+
231
+ MODEL RESP INPUT OUTPUT CACHE R CACHE W TOTAL
232
+ --------------------------------------------------------------------------------
233
+ claude-opus-4-8 4,732 1.4M 4.3M 572.0M 15.9M 593.7M
234
+ claude-sonnet-4-6 1,431 10.2k 786.0k 108.8M 2.8M 111.6M
235
+ ```
236
+
237
+ **The counts are normalized across the two tools**, because they don't report
238
+ the same way:
239
+
240
+ | field | meaning | claude | codex |
241
+ | ------------- | ------------------------------ | ------ | ----- |
242
+ | `input` | fresh (uncached) input tokens | as reported | `input_tokens` minus `cached_input_tokens`, which Codex nests inside it |
243
+ | `output` | output tokens | includes thinking | includes reasoning |
244
+ | `cache_read` | input served from cache | `cache_read_input_tokens` | `cached_input_tokens` |
245
+ | `cache_write` | input written to cache | `cache_creation_input_tokens` | never reported (always 0) |
246
+ | `reasoning` | thinking tokens, a *subset* of `output` | not broken out (always 0) | `reasoning_output_tokens` |
247
+
248
+ `total` is `input + output + cache_read + cache_write`; `reasoning` is
249
+ deliberately left out of it, since `output` already covers those tokens.
250
+
251
+ Two counting traps are handled for you, both of which inflate the numbers if
252
+ you read the logs naively:
253
+
254
+ - **Claude** writes one line per content block — thinking, text, and each tool
255
+ call — and every line of a single API response repeats the *identical* usage
256
+ block. Counting per line overstates usage roughly 2.6x, so responses are
257
+ deduplicated on their message id.
258
+ - **Codex** re-emits a stale `last_token_usage` on aborted and no-op turns that
259
+ its cumulative counter never absorbs, so a turn's real cost is read as the
260
+ rise in `total_token_usage` instead. The model name comes from the preceding
261
+ `turn_context` record (`session_meta` only names the provider).
262
+
263
+ What it can't tell you is cost — the logs carry no prices, and subscription
264
+ usage isn't billed per token anyway.
265
+
209
266
  ## Exporting for external tools
210
267
 
211
268
  `clockwork <provider> export` writes a single **self-describing, versioned**
@@ -258,17 +315,18 @@ for a combined view, so nothing is lost either way.
258
315
  - `totals.by_provider` breaks the grand totals down per provider; the grand
259
316
  `totals` stay the cross-provider sum.
260
317
 
261
- ### Export schema (`clockwork/v2`)
318
+ ### Export schema (`clockwork/v3`)
262
319
 
263
320
  ```jsonc
264
321
  {
265
- "schema": "clockwork/v2",
322
+ "schema": "clockwork/v3",
266
323
  "generated_at": "2026-07-06T00:30:00+02:00", // local ISO-8601
267
324
  "provider": "both", // "claude" | "codex" | "both"
268
325
  "providers": ["claude", "codex"], // sorted, distinct; ≥ 1 element
269
326
  "idle_threshold_min": 30,
270
327
  "detail": "raw", // raw | sessions | daily
271
328
  "anonymized": false,
329
+ "tokens": false, // true when --tokens was given (adds the fields below)
272
330
  "daily_tz": "UTC", // the "daily" buckets use UTC calendar dates
273
331
  "since": null, // ISO bound if --since was given, else null
274
332
  "until": null,
@@ -284,6 +342,19 @@ for a combined view, so nothing is lost either way.
284
342
  "first": 1780521570, "last": 1782130426 // epoch seconds
285
343
  },
286
344
  "daily": [ { "date": "2026-06-03", "minutes": 4.34, "prompts": 27 } ],
345
+ // every "tokens" block below appears only with --tokens
346
+ "tokens": {
347
+ "responses": 373, // API responses, deduplicated
348
+ "input": 31065, "output": 287747,
349
+ "cache_read": 20753836, "cache_write": 579725,
350
+ "reasoning": 0, // subset of output; Codex only
351
+ "total": 21652373, // input + output + cache_read + cache_write
352
+ "by_model": [ // biggest consumer first
353
+ { "model": "claude-opus-4-8", "responses": 238, "input": 30046,
354
+ "output": 177141, "cache_read": 13207329, "cache_write": 352749,
355
+ "reasoning": 0, "total": 13767265 }
356
+ ]
357
+ },
287
358
  "sessions": [ { "start": 1780521570, "end": 1780521830,
288
359
  "minutes": 4.34, "prompts": 27 } ], // detail >= sessions
289
360
  "prompts": [ 1780521570, 1780521582 ] // detail == raw
@@ -291,9 +362,12 @@ for a combined view, so nothing is lost either way.
291
362
  ],
292
363
  "totals": {
293
364
  "projects": 6, "minutes": 3392.97, "prompts": 4588, "sessions": 64,
365
+ "tokens": { /* same shape, summed across every project */ },
294
366
  "by_provider": {
295
- "claude": { "projects": 4, "minutes": 2500.0, "prompts": 3000, "sessions": 40 },
296
- "codex": { "projects": 2, "minutes": 892.97, "prompts": 1588, "sessions": 24 }
367
+ "claude": { "projects": 4, "minutes": 2500.0, "prompts": 3000, "sessions": 40,
368
+ "tokens": { /* ... */ } },
369
+ "codex": { "projects": 2, "minutes": 892.97, "prompts": 1588, "sessions": 24,
370
+ "tokens": { /* ... */ } }
297
371
  }
298
372
  }
299
373
  }
@@ -301,8 +375,14 @@ for a combined view, so nothing is lost either way.
301
375
 
302
376
  All instants are **UTC-based epoch seconds** (`new Date(sec * 1000)` in JS), so
303
377
  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.
378
+ contract — `clockwork/v2` was a breaking bump over `v1` (provider moved to the
379
+ project level), so tools should guard on it. `clockwork/v3` is **additive
380
+ only**: it adds the `tokens` flag and the `tokens` blocks described above, and a
381
+ v2 consumer reads a v3 bundle unchanged.
382
+
383
+ The per-day `tokens` buckets sum to the project's `tokens`, project totals sum
384
+ to `totals.by_provider`, and those sum to `totals.tokens` — at every level, and
385
+ per model.
306
386
 
307
387
  ## License
308
388
 
@@ -123,6 +123,7 @@ Options:
123
123
  form like 7d (7 days ago) or 2w (2 weeks ago)
124
124
  --detail <level> export granularity: raw | sessions | daily (default raw)
125
125
  --anonymize export: replace project paths with a hash id + generic name
126
+ --tokens Also report token usage and a per-model breakdown
126
127
  ```
127
128
 
128
129
  ### Examples
@@ -156,6 +157,10 @@ clockwork claude all --since 7d
156
157
  # A specific date range for one project
157
158
  clockwork claude ~/dev/myproject --since 2026-07-01 --until 2026-07-05
158
159
 
160
+ # Token and model usage, alongside the timings
161
+ clockwork claude all --tokens
162
+ clockwork both today --tokens
163
+
159
164
  # Machine-readable output — pipe into jq, a spreadsheet, or a dashboard
160
165
  clockwork codex all --json | jq '.projects[] | {project, minutes}'
161
166
  ```
@@ -188,6 +193,58 @@ usage still go to stderr), so clockwork composes with `jq`, cron jobs, or any
188
193
  dashboard. Exit codes are script-friendly: `0` on success, `1` when nothing
189
194
  matched, `2` for bad arguments.
190
195
 
196
+ ### Token & model usage (`--tokens`)
197
+
198
+ `--tokens` adds token counts and a per-model breakdown to any command. It reads
199
+ the usage each tool already records next to your prompts — nothing is estimated,
200
+ and no API is called.
201
+
202
+ ```
203
+ Tokens : 760.7M across 6,739 responses
204
+ In/Out : 1.6M in · 5.7M out
205
+ Cache : 731.7M read · 21.7M write
206
+ ========================================================================================
207
+
208
+ PROJECT TIME PROMPTS IN OUT CACHE TOTAL
209
+ ----------------------------------------------------------------------------------------
210
+ /Users/you/dev/alpha 54h 08m 3693 1.1M 2.8M 394.8M 398.7M
211
+ /Users/you/dev/beta 19h 01m 1414 196.4k 870.7k 121.5M 122.6M
212
+
213
+ MODEL RESP INPUT OUTPUT CACHE R CACHE W TOTAL
214
+ --------------------------------------------------------------------------------
215
+ claude-opus-4-8 4,732 1.4M 4.3M 572.0M 15.9M 593.7M
216
+ claude-sonnet-4-6 1,431 10.2k 786.0k 108.8M 2.8M 111.6M
217
+ ```
218
+
219
+ **The counts are normalized across the two tools**, because they don't report
220
+ the same way:
221
+
222
+ | field | meaning | claude | codex |
223
+ | ------------- | ------------------------------ | ------ | ----- |
224
+ | `input` | fresh (uncached) input tokens | as reported | `input_tokens` minus `cached_input_tokens`, which Codex nests inside it |
225
+ | `output` | output tokens | includes thinking | includes reasoning |
226
+ | `cache_read` | input served from cache | `cache_read_input_tokens` | `cached_input_tokens` |
227
+ | `cache_write` | input written to cache | `cache_creation_input_tokens` | never reported (always 0) |
228
+ | `reasoning` | thinking tokens, a *subset* of `output` | not broken out (always 0) | `reasoning_output_tokens` |
229
+
230
+ `total` is `input + output + cache_read + cache_write`; `reasoning` is
231
+ deliberately left out of it, since `output` already covers those tokens.
232
+
233
+ Two counting traps are handled for you, both of which inflate the numbers if
234
+ you read the logs naively:
235
+
236
+ - **Claude** writes one line per content block — thinking, text, and each tool
237
+ call — and every line of a single API response repeats the *identical* usage
238
+ block. Counting per line overstates usage roughly 2.6x, so responses are
239
+ deduplicated on their message id.
240
+ - **Codex** re-emits a stale `last_token_usage` on aborted and no-op turns that
241
+ its cumulative counter never absorbs, so a turn's real cost is read as the
242
+ rise in `total_token_usage` instead. The model name comes from the preceding
243
+ `turn_context` record (`session_meta` only names the provider).
244
+
245
+ What it can't tell you is cost — the logs carry no prices, and subscription
246
+ usage isn't billed per token anyway.
247
+
191
248
  ## Exporting for external tools
192
249
 
193
250
  `clockwork <provider> export` writes a single **self-describing, versioned**
@@ -240,17 +297,18 @@ for a combined view, so nothing is lost either way.
240
297
  - `totals.by_provider` breaks the grand totals down per provider; the grand
241
298
  `totals` stay the cross-provider sum.
242
299
 
243
- ### Export schema (`clockwork/v2`)
300
+ ### Export schema (`clockwork/v3`)
244
301
 
245
302
  ```jsonc
246
303
  {
247
- "schema": "clockwork/v2",
304
+ "schema": "clockwork/v3",
248
305
  "generated_at": "2026-07-06T00:30:00+02:00", // local ISO-8601
249
306
  "provider": "both", // "claude" | "codex" | "both"
250
307
  "providers": ["claude", "codex"], // sorted, distinct; ≥ 1 element
251
308
  "idle_threshold_min": 30,
252
309
  "detail": "raw", // raw | sessions | daily
253
310
  "anonymized": false,
311
+ "tokens": false, // true when --tokens was given (adds the fields below)
254
312
  "daily_tz": "UTC", // the "daily" buckets use UTC calendar dates
255
313
  "since": null, // ISO bound if --since was given, else null
256
314
  "until": null,
@@ -266,6 +324,19 @@ for a combined view, so nothing is lost either way.
266
324
  "first": 1780521570, "last": 1782130426 // epoch seconds
267
325
  },
268
326
  "daily": [ { "date": "2026-06-03", "minutes": 4.34, "prompts": 27 } ],
327
+ // every "tokens" block below appears only with --tokens
328
+ "tokens": {
329
+ "responses": 373, // API responses, deduplicated
330
+ "input": 31065, "output": 287747,
331
+ "cache_read": 20753836, "cache_write": 579725,
332
+ "reasoning": 0, // subset of output; Codex only
333
+ "total": 21652373, // input + output + cache_read + cache_write
334
+ "by_model": [ // biggest consumer first
335
+ { "model": "claude-opus-4-8", "responses": 238, "input": 30046,
336
+ "output": 177141, "cache_read": 13207329, "cache_write": 352749,
337
+ "reasoning": 0, "total": 13767265 }
338
+ ]
339
+ },
269
340
  "sessions": [ { "start": 1780521570, "end": 1780521830,
270
341
  "minutes": 4.34, "prompts": 27 } ], // detail >= sessions
271
342
  "prompts": [ 1780521570, 1780521582 ] // detail == raw
@@ -273,9 +344,12 @@ for a combined view, so nothing is lost either way.
273
344
  ],
274
345
  "totals": {
275
346
  "projects": 6, "minutes": 3392.97, "prompts": 4588, "sessions": 64,
347
+ "tokens": { /* same shape, summed across every project */ },
276
348
  "by_provider": {
277
- "claude": { "projects": 4, "minutes": 2500.0, "prompts": 3000, "sessions": 40 },
278
- "codex": { "projects": 2, "minutes": 892.97, "prompts": 1588, "sessions": 24 }
349
+ "claude": { "projects": 4, "minutes": 2500.0, "prompts": 3000, "sessions": 40,
350
+ "tokens": { /* ... */ } },
351
+ "codex": { "projects": 2, "minutes": 892.97, "prompts": 1588, "sessions": 24,
352
+ "tokens": { /* ... */ } }
279
353
  }
280
354
  }
281
355
  }
@@ -283,8 +357,14 @@ for a combined view, so nothing is lost either way.
283
357
 
284
358
  All instants are **UTC-based epoch seconds** (`new Date(sec * 1000)` in JS), so
285
359
  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.
360
+ contract — `clockwork/v2` was a breaking bump over `v1` (provider moved to the
361
+ project level), so tools should guard on it. `clockwork/v3` is **additive
362
+ only**: it adds the `tokens` flag and the `tokens` blocks described above, and a
363
+ v2 consumer reads a v3 bundle unchanged.
364
+
365
+ The per-day `tokens` buckets sum to the project's `tokens`, project totals sum
366
+ to `totals.by_provider`, and those sum to `totals.tokens` — at every level, and
367
+ per model.
288
368
 
289
369
  ## License
290
370
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "clockwork-cli"
7
- version = "0.2.0"
7
+ version = "0.3.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"]