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.
- {clockwork_cli-0.2.0/src/clockwork_cli.egg-info → clockwork_cli-0.3.0}/PKG-INFO +87 -7
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/README.md +86 -6
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/pyproject.toml +5 -1
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/src/clockwork_cli/__init__.py +607 -123
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0/src/clockwork_cli.egg-info}/PKG-INFO +87 -7
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/src/clockwork_cli.egg-info/SOURCES.txt +2 -1
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/tests/test_export.py +95 -6
- clockwork_cli-0.3.0/tests/test_tokens.py +259 -0
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/LICENSE +0 -0
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/setup.cfg +0 -0
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/src/clockwork_cli/__main__.py +0 -0
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/src/clockwork_cli.egg-info/dependency_links.txt +0 -0
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/src/clockwork_cli.egg-info/entry_points.txt +0 -0
- {clockwork_cli-0.2.0 → clockwork_cli-0.3.0}/src/clockwork_cli.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: clockwork-cli
|
|
3
|
-
Version: 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/
|
|
318
|
+
### Export schema (`clockwork/v3`)
|
|
262
319
|
|
|
263
320
|
```jsonc
|
|
264
321
|
{
|
|
265
|
-
"schema": "clockwork/
|
|
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
|
-
|
|
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`
|
|
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/
|
|
300
|
+
### Export schema (`clockwork/v3`)
|
|
244
301
|
|
|
245
302
|
```jsonc
|
|
246
303
|
{
|
|
247
|
-
"schema": "clockwork/
|
|
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
|
-
|
|
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`
|
|
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.
|
|
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"]
|