clockwork-cli 0.3.0__tar.gz → 0.4.1__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.3.0
3
+ Version: 0.4.1
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
 
@@ -252,9 +272,11 @@ Two counting traps are handled for you, both of which inflate the numbers if
252
272
  you read the logs naively:
253
273
 
254
274
  - **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.
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.
258
280
  - **Codex** re-emits a stale `last_token_usage` on aborted and no-op turns that
259
281
  its cumulative counter never absorbs, so a turn's real cost is read as the
260
282
  rise in `total_token_usage` instead. The model name comes from the preceding
@@ -337,11 +359,15 @@ for a combined view, so nothing is lost either way.
337
359
  "name": "myproject", // basename, or "project-N" when anonymized
338
360
  "path": "/Users/you/dev/myproject", // omitted when anonymized
339
361
  "totals": {
340
- "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,
341
366
  "active_days": 12,
342
367
  "first": 1780521570, "last": 1782130426 // epoch seconds
343
368
  },
344
- "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 } ],
345
371
  // every "tokens" block below appears only with --tokens
346
372
  "tokens": {
347
373
  "responses": 373, // API responses, deduplicated
@@ -356,23 +382,32 @@ for a combined view, so nothing is lost either way.
356
382
  ]
357
383
  },
358
384
  "sessions": [ { "start": 1780521570, "end": 1780521830,
359
- "minutes": 4.34, "prompts": 27 } ], // detail >= sessions
360
- "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
361
389
  }
362
390
  ],
363
391
  "totals": {
364
- "projects": 6, "minutes": 3392.97, "prompts": 4588, "sessions": 64,
392
+ "projects": 6, "minutes": 3392.97, "prompts": 4588, "human_prompts": 950,
393
+ "sessions": 64,
365
394
  "tokens": { /* same shape, summed across every project */ },
366
395
  "by_provider": {
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": { /* ... */ } }
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": { /* ... */ } }
371
400
  }
372
401
  }
373
402
  }
374
403
  ```
375
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
+
376
411
  All instants are **UTC-based epoch seconds** (`new Date(sec * 1000)` in JS), so
377
412
  the consumer picks the display timezone. The `schema` field is the version
378
413
  contract — `clockwork/v2` was a breaking bump over `v1` (provider moved to the
@@ -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
 
@@ -234,9 +254,11 @@ Two counting traps are handled for you, both of which inflate the numbers if
234
254
  you read the logs naively:
235
255
 
236
256
  - **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.
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.
240
262
  - **Codex** re-emits a stale `last_token_usage` on aborted and no-op turns that
241
263
  its cumulative counter never absorbs, so a turn's real cost is read as the
242
264
  rise in `total_token_usage` instead. The model name comes from the preceding
@@ -319,11 +341,15 @@ for a combined view, so nothing is lost either way.
319
341
  "name": "myproject", // basename, or "project-N" when anonymized
320
342
  "path": "/Users/you/dev/myproject", // omitted when anonymized
321
343
  "totals": {
322
- "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,
323
348
  "active_days": 12,
324
349
  "first": 1780521570, "last": 1782130426 // epoch seconds
325
350
  },
326
- "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 } ],
327
353
  // every "tokens" block below appears only with --tokens
328
354
  "tokens": {
329
355
  "responses": 373, // API responses, deduplicated
@@ -338,23 +364,32 @@ for a combined view, so nothing is lost either way.
338
364
  ]
339
365
  },
340
366
  "sessions": [ { "start": 1780521570, "end": 1780521830,
341
- "minutes": 4.34, "prompts": 27 } ], // detail >= sessions
342
- "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
343
371
  }
344
372
  ],
345
373
  "totals": {
346
- "projects": 6, "minutes": 3392.97, "prompts": 4588, "sessions": 64,
374
+ "projects": 6, "minutes": 3392.97, "prompts": 4588, "human_prompts": 950,
375
+ "sessions": 64,
347
376
  "tokens": { /* same shape, summed across every project */ },
348
377
  "by_provider": {
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": { /* ... */ } }
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": { /* ... */ } }
353
382
  }
354
383
  }
355
384
  }
356
385
  ```
357
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
+
358
393
  All instants are **UTC-based epoch seconds** (`new Date(sec * 1000)` in JS), so
359
394
  the consumer picks the display timezone. The `schema` field is the version
360
395
  contract — `clockwork/v2` was a breaking bump over `v1` (provider moved to the
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "clockwork-cli"
7
- version = "0.3.0"
7
+ version = "0.4.1"
8
8
  description = "Mine your Claude Code and Codex session logs to estimate active time"
9
9
  readme = "README.md"
10
10
  license = "MIT"