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.
- {clockwork_cli-0.2.1/src/clockwork_cli.egg-info → clockwork_cli-0.4.0}/PKG-INFO +134 -19
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.0}/README.md +133 -18
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.0}/pyproject.toml +5 -1
- clockwork_cli-0.4.0/src/clockwork_cli/__init__.py +1763 -0
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.0/src/clockwork_cli.egg-info}/PKG-INFO +134 -19
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.0}/src/clockwork_cli.egg-info/SOURCES.txt +4 -1
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.0}/tests/test_export.py +101 -6
- clockwork_cli-0.4.0/tests/test_paths.py +90 -0
- clockwork_cli-0.4.0/tests/test_prompts.py +168 -0
- clockwork_cli-0.4.0/tests/test_tokens.py +357 -0
- clockwork_cli-0.2.1/src/clockwork_cli/__init__.py +0 -1042
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.0}/LICENSE +0 -0
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.0}/setup.cfg +0 -0
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.0}/src/clockwork_cli/__main__.py +0 -0
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.0}/src/clockwork_cli.egg-info/dependency_links.txt +0 -0
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.0}/src/clockwork_cli.egg-info/entry_points.txt +0 -0
- {clockwork_cli-0.2.1 → clockwork_cli-0.4.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.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
|
|
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
|
|
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.
|
|
78
|
-
>
|
|
79
|
-
>
|
|
80
|
-
>
|
|
81
|
-
>
|
|
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/
|
|
340
|
+
### Export schema (`clockwork/v3`)
|
|
262
341
|
|
|
263
342
|
```jsonc
|
|
264
343
|
{
|
|
265
|
-
"schema": "clockwork/
|
|
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,
|
|
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
|
|
289
|
-
|
|
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, "
|
|
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,
|
|
296
|
-
|
|
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`
|
|
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
|
|
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
|
|
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.
|
|
60
|
-
>
|
|
61
|
-
>
|
|
62
|
-
>
|
|
63
|
-
>
|
|
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/
|
|
322
|
+
### Export schema (`clockwork/v3`)
|
|
244
323
|
|
|
245
324
|
```jsonc
|
|
246
325
|
{
|
|
247
|
-
"schema": "clockwork/
|
|
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,
|
|
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
|
|
271
|
-
|
|
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, "
|
|
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,
|
|
278
|
-
|
|
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`
|
|
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.
|
|
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"]
|