@drakulavich/cogload 0.10.0
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.
- package/CHANGELOG.md +303 -0
- package/LICENSE +21 -0
- package/README.md +301 -0
- package/assets/characters.webp +0 -0
- package/assets/fonts/LICENSE-inter.txt +92 -0
- package/assets/fonts/LICENSE-jetbrains-mono.txt +93 -0
- package/assets/fonts/inter-400.woff2 +0 -0
- package/assets/fonts/inter-700.woff2 +0 -0
- package/assets/fonts/inter-800.woff2 +0 -0
- package/assets/fonts/jetbrains-mono-500.woff2 +0 -0
- package/package.json +30 -0
- package/src/cli/args.ts +155 -0
- package/src/cli/commands.io.ts +99 -0
- package/src/cli/index.ts +58 -0
- package/src/cli/timing.ts +18 -0
- package/src/cli/zapara.ts +5 -0
- package/src/lib/card/card.ts +172 -0
- package/src/lib/card/cardhtml.ts +130 -0
- package/src/lib/card/image.io.ts +134 -0
- package/src/lib/card/index.ts +3 -0
- package/src/lib/metrics/analyze.ts +17 -0
- package/src/lib/metrics/derive.ts +221 -0
- package/src/lib/metrics/index.ts +3 -0
- package/src/lib/metrics/score.ts +55 -0
- package/src/lib/report/index.ts +1 -0
- package/src/lib/report/report.io.ts +82 -0
- package/src/lib/status/index.ts +2 -0
- package/src/lib/status/status.ts +52 -0
- package/src/lib/status/statusfile.io.ts +38 -0
- package/src/lib/text/format.ts +16 -0
- package/src/lib/text/index.ts +2 -0
- package/src/lib/text/render.ts +120 -0
- package/src/lib/transcripts/cache.io.ts +256 -0
- package/src/lib/transcripts/index.ts +3 -0
- package/src/lib/transcripts/parse.ts +138 -0
- package/src/lib/transcripts/scan.io.ts +75 -0
- package/src/lib/types.ts +22 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|
5
|
+
|
|
6
|
+
## [Unreleased]
|
|
7
|
+
|
|
8
|
+
## [0.10.0] - 2026-10-05
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- The `cognitive-load` Claude Code plugin shows the current load above the
|
|
12
|
+
prompt. Install it from this repository's marketplace
|
|
13
|
+
(`/plugin marketplace add drakulavich/cogload`, then
|
|
14
|
+
`/plugin install cognitive-load@cogload`); it is not part of the npm package.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
- zapara is now cogload: the package is `@drakulavich/cogload`, the command
|
|
18
|
+
`cogload`, the data directory `~/.claude/cogload/`, the card
|
|
19
|
+
`cogload-card.png`, the plugin marketplace `cogload`. The cache starts over
|
|
20
|
+
with one full scan. Run `bun remove -g @drakulavich/zapara` before installing.
|
|
21
|
+
A `zapara` command stays until 1.0.0 and says on stderr that it was renamed.
|
|
22
|
+
- The `cognitive-load` plugin holds the prompts you type for ten minutes
|
|
23
|
+
after a 40-minute streak or a Fried hour. `override: <reason>` goes on and
|
|
24
|
+
is counted in the band; `/overrides` lists the reasons of the last 14 days.
|
|
25
|
+
The band is hidden while the last hour is calm.
|
|
26
|
+
- The `cognitive-load` band reads the load every minute, one `cogload status`
|
|
27
|
+
run a minute across sessions, so a rest starts at the 40th minute even
|
|
28
|
+
between turns, and the band counts the rest down.
|
|
29
|
+
|
|
30
|
+
## [0.9.0] - 2026-09-27
|
|
31
|
+
|
|
32
|
+
### Changed
|
|
33
|
+
- The Night Owl's motto is "The best commits happen after dark." It used to
|
|
34
|
+
repeat the sentence before it: "… of your hours late at night. The best
|
|
35
|
+
commits happen late at night."
|
|
36
|
+
- zapara needs Bun 1.4.2 or newer, up from 1.4.0. CI checks one version, the
|
|
37
|
+
one it runs on.
|
|
38
|
+
- `--help` says a pipe gets JSON for the grid and a day only; `card` and
|
|
39
|
+
`status` in a pipe print their usual lines.
|
|
40
|
+
- The status file's `peak` counts the last sixty minutes as well as the
|
|
41
|
+
day's calendar hours, so `index` is never above it. Sixty minutes that
|
|
42
|
+
straddle two hours can score above both, and a status line could read
|
|
43
|
+
`load 13 · peak 11`. `peak` in `--json`, the grid and the day table
|
|
44
|
+
still covers calendar hours only.
|
|
45
|
+
|
|
46
|
+
### Fixed
|
|
47
|
+
- The card no longer shows a highlight worth nothing. A Night Owl whose hours
|
|
48
|
+
were all at 23:xx showed `0m / longest streak` as its second panel. A second
|
|
49
|
+
or third highlight that is zero is now left out, and the panels left share
|
|
50
|
+
the row; the character's own first number always shows, so a card has
|
|
51
|
+
three, two or one panels.
|
|
52
|
+
- A transcript larger than 2 GiB is skipped like an unreadable file instead of
|
|
53
|
+
failing every command, `status` included, with `Cannot create a string longer
|
|
54
|
+
than 2147483647 characters`. The rest of the report stands, and zapara no
|
|
55
|
+
longer reads such a file into memory at all.
|
|
56
|
+
- `zapara status` no longer cuts a live streak at local midnight. Its day
|
|
57
|
+
looked back only to 21:00 the evening before, so a six-hour streak read
|
|
58
|
+
`"streakMin":360` at 23:51 and 230 at 00:51 while you kept typing. `status`
|
|
59
|
+
now traces the streak back to its first action, up to 25 hours before now;
|
|
60
|
+
no other number in the file changes.
|
|
61
|
+
- `zapara status` writes a streak longer than 25 hours as `"streakMin":1500`,
|
|
62
|
+
the ceiling the status file promises its readers. It used to write up to
|
|
63
|
+
1620 late in the evening, and a reader that decodes the file strictly,
|
|
64
|
+
like pult, dropped the whole line as no data.
|
|
65
|
+
- A run that finds `~/.claude/zapara/cache.db` unreadable deletes it only
|
|
66
|
+
if it is still the same file. Two runs that started on a damaged cache
|
|
67
|
+
could race, and the later one deleted the cache the earlier one had just
|
|
68
|
+
recreated, so that run went without a cache. The output was right either
|
|
69
|
+
way.
|
|
70
|
+
- `zapara card` no longer counts records timestamped after the moment it
|
|
71
|
+
runs, which the grid, the day and `status` already left out. A transcript
|
|
72
|
+
from a machine whose clock runs ahead could put hours on the card that no
|
|
73
|
+
other view showed.
|
|
74
|
+
- The Night Owl's card says "late at night" instead of "after midnight" in
|
|
75
|
+
its sentence, caption and motto. The late hours are 23 and 0 to 5, so a
|
|
76
|
+
card whose late hours were all 23:xx read "100% of your hours after
|
|
77
|
+
midnight".
|
|
78
|
+
- The Marathoner's sentence takes its calm share from the spectrum under it,
|
|
79
|
+
so one card no longer says 33% calm in the sentence and 34% in the legend.
|
|
80
|
+
- A level with any hours shows at least 1% on the card's spectrum. One fried
|
|
81
|
+
hour among 200 calm ones used to read `100% calm · 0% fried` beside a
|
|
82
|
+
Fried peak.
|
|
83
|
+
- A card whose remaining highlight candidates all score zero shows the
|
|
84
|
+
character's two highlights instead of a third reading `1 / sessions at
|
|
85
|
+
once`, and a highlight whose value is 1 has a singular caption
|
|
86
|
+
(`1 / session at once`).
|
|
87
|
+
- `zapara card` replaces a symlink at the card's path instead of writing the
|
|
88
|
+
picture into the file it points to. An archive unpacked into Downloads
|
|
89
|
+
could leave a `zapara-card.png` link that aimed the card at another file.
|
|
90
|
+
- The card's file mode follows your umask. With the cache on it used to come
|
|
91
|
+
out 0600, because the cache narrowed the umask for the whole run; the cache
|
|
92
|
+
now sets its own files' modes and leaves the umask alone.
|
|
93
|
+
- Ctrl-C while `zapara card` draws the picture removes its temporary page
|
|
94
|
+
instead of leaving it in the temporary directory.
|
|
95
|
+
- Without `--out`, a card that Downloads cannot take says `cannot write
|
|
96
|
+
zapara-card.png to Downloads: pass --out <path>` instead of pointing at an
|
|
97
|
+
`--out` directory the person never gave.
|
|
98
|
+
- `card --json --out me.png` is a usage error, `--json writes no file; drop
|
|
99
|
+
--out`, instead of printing the data, writing nothing and exiting 0.
|
|
100
|
+
- A `card` window with no activity names its dates, `no activity from
|
|
101
|
+
2026-08-01 to 2026-08-31`, instead of `no activity in the last 31 days`,
|
|
102
|
+
which was false for a window that ended in the past.
|
|
103
|
+
- `card --json` over a window with no activity prints `null` and exits 0,
|
|
104
|
+
so a script gets a document either way. The picture still exits 1.
|
|
105
|
+
- A projects directory that can be listed but not entered (mode 444) says
|
|
106
|
+
`projects directory cannot be read (check its permissions)` and exits 1,
|
|
107
|
+
as one with mode 000 does, instead of reporting no activity.
|
|
108
|
+
- `--projects` pointing at a file, such as one transcript, says `projects
|
|
109
|
+
path is not a directory` instead of `projects directory not found`.
|
|
110
|
+
- A transcript that starts with a UTF-8 byte order mark, as an editor may
|
|
111
|
+
save it, keeps its first record instead of dropping it as malformed.
|
|
112
|
+
- A cache row whose events no longer decode is rebuilt by the next run
|
|
113
|
+
instead of missing on every run until its transcript changed.
|
|
114
|
+
- A `cache.db` corrupt past its header is deleted and created again, as
|
|
115
|
+
one that fails to open already was, instead of leaving the cache off for
|
|
116
|
+
good. When a lookup fails, `--verbose` prints `cache off` instead of
|
|
117
|
+
counting every file as a miss.
|
|
118
|
+
- zapara sets the modes of `~/.claude/zapara` (0700) and `cache.db` (0600)
|
|
119
|
+
only when it creates them, instead of resetting them on every run;
|
|
120
|
+
`zapara status` no longer resets the directory either. `status.json`
|
|
121
|
+
is still written 0600 each time.
|
|
122
|
+
- The week grid ends with `as of HH:MM, this hour is still running` when
|
|
123
|
+
`--to` names a day after today, as the JSON's `asOf` already did.
|
|
124
|
+
- A window across a calendar day the time zone skipped (Samoa went from 29
|
|
125
|
+
to 31 December 2011) lists that date once as an empty day, instead of
|
|
126
|
+
listing the next day twice with its counts doubled.
|
|
127
|
+
- An Enter pressed while the card is being drawn no longer answers `open
|
|
128
|
+
it? [Y/n]` before the question is shown: input typed before the question
|
|
129
|
+
is discarded.
|
|
130
|
+
- An empty value, as in `--projects ''` or `--projects=`, is a usage error,
|
|
131
|
+
`--projects needs a value`, exit 2, instead of `projects directory not
|
|
132
|
+
found`.
|
|
133
|
+
|
|
134
|
+
## [0.8.1] - 2026-09-27
|
|
135
|
+
|
|
136
|
+
### Changed
|
|
137
|
+
- `--verbose` now accounts for the whole run. New rows time Bun's start
|
|
138
|
+
and zapara's module load, opening the cache, and saving to it, and
|
|
139
|
+
`zapara status` adds the write of its status file. The `cache` row now
|
|
140
|
+
carries the milliseconds spent looking files up in the cache, so `read`
|
|
141
|
+
counts only the reads of files the cache missed.
|
|
142
|
+
- A PNG or WebP card loads its page from a file in the temporary directory
|
|
143
|
+
instead of a data: URL, and zapara removes that file when the render ends,
|
|
144
|
+
whether it succeeded or failed. With six processes rendering at once, 0
|
|
145
|
+
of 288 renders from a file hung, against about 1 in 48 from a data: URL,
|
|
146
|
+
which ended in `render timed out`. The median render is about 120 ms
|
|
147
|
+
slower. When the temporary directory cannot be written, zapara exits 1
|
|
148
|
+
with `cannot draw the card: the temporary directory is not writable`.
|
|
149
|
+
- When `zapara card` finds no browser engine, the message suggests any
|
|
150
|
+
Chromium browser, such as Chrome or Edge, instead of only Google Chrome.
|
|
151
|
+
|
|
152
|
+
## [0.8.0] - 2026-09-26
|
|
153
|
+
|
|
154
|
+
### Added
|
|
155
|
+
- zapara caches each transcript's parsed events between runs, in
|
|
156
|
+
`~/.claude/zapara/cache.db`, and reparses a file only when it has changed.
|
|
157
|
+
A row is a hit when its size, modification time and the SHA-256 of its
|
|
158
|
+
last 4 KiB all match the cached one; the row is keyed by the transcript's
|
|
159
|
+
device and inode, never by its path. On one machine, with nothing changed
|
|
160
|
+
since the run before, `zapara card --json --verbose` went from 4362 ms
|
|
161
|
+
(816 files read, 0 cache hits) to 246 ms (0 files read, 816 hits).
|
|
162
|
+
`--no-cache` runs without reading or writing the cache, and `--verbose`
|
|
163
|
+
gains a `cache` line with the hit and miss counts, or `off`.
|
|
164
|
+
|
|
165
|
+
### Changed
|
|
166
|
+
- A PNG card renders in about 0.7 s instead of 1.1 s on macOS. zapara opens
|
|
167
|
+
one browser view instead of two, and writes WebKit's screenshot as it is
|
|
168
|
+
when it already has the card's size, instead of encoding the same PNG a
|
|
169
|
+
second time. The file is about 2.6 MB instead of 2.1 MB: WebKit's PNG
|
|
170
|
+
encoder compresses less, and the pixels are the same.
|
|
171
|
+
|
|
172
|
+
## [0.7.4] - 2026-09-26
|
|
173
|
+
|
|
174
|
+
### Changed
|
|
175
|
+
- On a high-density screen, `zapara card` draws the picture at its final size
|
|
176
|
+
instead of at double size and scaling it down. The PNG render on a Mac went
|
|
177
|
+
from about 3.4 s to 1.6 s. The picture is the same.
|
|
178
|
+
|
|
179
|
+
### Fixed
|
|
180
|
+
- `--verbose` no longer counts the wait at `open it? [Y/n]` in the `total` row.
|
|
181
|
+
|
|
182
|
+
## [0.7.3] - 2026-09-26
|
|
183
|
+
|
|
184
|
+
### Added
|
|
185
|
+
- `--verbose` prints timings and counts to stderr after the output, with no
|
|
186
|
+
path in them: files scanned and read, megabytes, milliseconds per stage,
|
|
187
|
+
versions, platform and CPU count. It is meant for diagnosing a slow run on
|
|
188
|
+
someone else's machine.
|
|
189
|
+
- `zapara card` says `drawing the card…` on a terminal's stderr while the
|
|
190
|
+
browser engine renders the picture, which takes a few seconds.
|
|
191
|
+
|
|
192
|
+
## [0.7.2] - 2026-09-26
|
|
193
|
+
|
|
194
|
+
### Changed
|
|
195
|
+
- Transcripts are read sixteen at a time instead of one by one. On a machine
|
|
196
|
+
with 1.6 GB of transcripts in a 14-day window, reading took 0.9 s instead
|
|
197
|
+
of 5.4 s.
|
|
198
|
+
- Transcript lines older than the window's three-hour look-back are skipped
|
|
199
|
+
before parsing, except assistant replies, whose request ids dedupe output
|
|
200
|
+
tokens. A long session's file holds its whole history, and on one machine
|
|
201
|
+
59% of what a 14-day window read was such history. Results are unchanged.
|
|
202
|
+
Together with parallel reads, `zapara card --json` there went from 5.6 s to
|
|
203
|
+
about 2 s.
|
|
204
|
+
|
|
205
|
+
## [0.7.1] - 2026-09-25
|
|
206
|
+
|
|
207
|
+
### Added
|
|
208
|
+
- `zapara --help` ends with where to report bugs, share ideas and star the
|
|
209
|
+
project.
|
|
210
|
+
|
|
211
|
+
### Fixed
|
|
212
|
+
- Sessions started by a script through `claude -p` or the Agent SDK no longer
|
|
213
|
+
count as yours. A batch of 200 of them showed up as "204 sessions at once"
|
|
214
|
+
and inflated that hour's prompts, context switches and index.
|
|
215
|
+
|
|
216
|
+
## [0.7.0] - 2026-09-23
|
|
217
|
+
|
|
218
|
+
### Added
|
|
219
|
+
- In a terminal, `zapara card` asks `open it? [Y/n]` and opens the picture in
|
|
220
|
+
the default viewer on Enter. Pipes, scripts and Windows are never asked.
|
|
221
|
+
|
|
222
|
+
### Changed
|
|
223
|
+
- `zapara card` writes to `~/Downloads/zapara-card.png` instead of the current
|
|
224
|
+
directory, and says `wrote zapara-card.png to Downloads`. Without that
|
|
225
|
+
folder it asks for `--out`.
|
|
226
|
+
|
|
227
|
+
## [0.6.0] - 2026-09-22
|
|
228
|
+
|
|
229
|
+
### Changed
|
|
230
|
+
- The week grid dims a day no hour scored in, so a weekend recedes behind the
|
|
231
|
+
working days around it.
|
|
232
|
+
|
|
233
|
+
## [0.5.0] - 2026-09-22
|
|
234
|
+
|
|
235
|
+
### Changed
|
|
236
|
+
- The week grid's `peak` column is painted in a TTY with the color of the level its index falls in, by the same thresholds `zapara status` reads a level from; `--no-color` and a pipe are unchanged.
|
|
237
|
+
- The status file's `index` and `level` are the load of the sixty minutes ending at `asOf`, not of the calendar hour that contains it: the number no longer drops to nothing at every hour boundary (90 at 11:59:30, 6 at 12:00:30 on one machine) and no longer climbs through the hour as the bucket fills. `Day.live` in `--json` carries that bucket on the open day. Same formula, same norms; `schema` stays 1.
|
|
238
|
+
|
|
239
|
+
## [0.4.0] - 2026-09-21
|
|
240
|
+
|
|
241
|
+
### Changed
|
|
242
|
+
- Streak norm recalibrated for the presence rule: 40 minutes of your own uninterrupted actions now score the full streak points (was 120, the p90 of the old rule that let agent activity keep a streak alive; the p90 under the new rule is 33 on one machine and 48 on another, and 40 sits between them).
|
|
243
|
+
- Presence counts every human action, not only prompts: an interrupt, a tool rejection and an answer to a question or a plan hold a streak open and fill active minutes the same way a prompt does. They remain decisions where they already were; nothing is counted twice.
|
|
244
|
+
- An hour's streak is the longest streak seen in it, not the one it happened to end on. A single prompt after a break no longer erases the run the hour held, nor the streak points of that hour's index.
|
|
245
|
+
- The status file's streak is live: it counts from the first action of the streak you are in up to `asOf`, and resets to `0` once you have been away for more than ten minutes. Before, it was the current hour's bucket, so it fell to zero at every hour boundary.
|
|
246
|
+
- `Day.presence` in `--json`: the day's last human action and the start of the streak it belongs to, as instants, or `null` on a day with no action of yours.
|
|
247
|
+
|
|
248
|
+
### Fixed
|
|
249
|
+
- The card's longest streak is no longer under-reported: a run that ended in an hour where another began used to be measured only up to the end of the hour before.
|
|
250
|
+
- The status line's streak no longer drops to zero at each hour boundary.
|
|
251
|
+
- `card --out` into a directory that does not exist or refuses the write says `cannot write the card: check the --out directory` instead of printing the full path back in a file-system error.
|
|
252
|
+
- A permission-mode switch made before the first message of a session counts: it is attributed to the first timestamped record that follows, instead of vanishing.
|
|
253
|
+
- A transcript whose modification time is outside the window is read when its last record is a big one: the rescue that looks for the last timestamp reads 64 KB from the end instead of 4 KB, so a day that ended on a large tool result is no longer dropped in full.
|
|
254
|
+
- An output-token count that is not a finite non-negative integer is ignored instead of poisoning the day: a corrupt transcript could put `NaN` in the token column and `null` in the JSON, beside a made-up level.
|
|
255
|
+
- A prompt with a pasted screenshot counts again: the image block comes before the typed text, and such prompts were read as no text at all, so a day spent pasting screenshots showed no prompts and no active minutes.
|
|
256
|
+
|
|
257
|
+
## [0.3.1] - 2026-09-19
|
|
258
|
+
|
|
259
|
+
### Changed
|
|
260
|
+
- Streak and active minutes count your presence, not the agent's: a streak is your prompts no more than 10 minutes apart across sessions, and active minutes are the five-minute slots those streaks cover. Agent work while you are away no longer keeps a streak alive or fills the day.
|
|
261
|
+
|
|
262
|
+
## [0.3.0] - 2026-09-19
|
|
263
|
+
|
|
264
|
+
### Added
|
|
265
|
+
- A window that includes today says when the snapshot was taken: `asOf` on today's JSON entry and an `as of HH:MM, this hour is still running` line under the tables.
|
|
266
|
+
- `zapara status` writes today's load to `~/.claude/zapara/status.json` for a status line to read; the file format and the reader's refresh contract are in the spec.
|
|
267
|
+
|
|
268
|
+
### Fixed
|
|
269
|
+
- A window or output flag given twice (`--days 3 --days 5`) is a usage error, `--days given twice`, instead of the last value winning silently.
|
|
270
|
+
- A transcript whose modification time is older than the window is still read when the last timestamp in it falls inside the window; before, a restored or synced file was dropped in full without a word.
|
|
271
|
+
|
|
272
|
+
## [0.2.0] - 2026-09-18
|
|
273
|
+
|
|
274
|
+
### Changed
|
|
275
|
+
- The command line is the window and the view, not names for windows: `zapara` is the grid of the last 7 days, `zapara --days 30`, `zapara --to 2026-09-14` or `zapara --from 2026-09-01 --to 2026-09-14` any window up to 90 days; `zapara today`, `zapara yesterday` or `zapara 2026-09-14` one day, hour by hour; `zapara card` the picture, with the same window flags. `week` and `day` are gone. A date is `YYYY-MM-DD`, `today` or `yesterday` everywhere; `--days=30` works beside `--days 30`; `-V` beside `--version`.
|
|
276
|
+
- A usage error prints its line and `run 'zapara --help' for usage`, exit 2, instead of the whole usage screen; `--help` is one screen under 80 columns.
|
|
277
|
+
|
|
278
|
+
### Fixed
|
|
279
|
+
- `--days -1` is answered by the range message (`--days must be 1..90, got -1`) instead of `--days needs a value`: a negative number is a value, not a flag.
|
|
280
|
+
- A projects directory that exists but cannot be read says so (`projects directory cannot be read (check its permissions)`, exit 1) instead of `not found`; the message still names no path.
|
|
281
|
+
- The README's screencast and card show on npmjs.com: both images use absolute raw.githubusercontent.com URLs, and the demo files left Git LFS, whose objects the raw endpoint serves as pointer text.
|
|
282
|
+
|
|
283
|
+
## [0.1.0] - 2026-09-18
|
|
284
|
+
|
|
285
|
+
### Added
|
|
286
|
+
- Project scaffold: Bun runs `src/index.ts` directly, `bun run check` typechecks and tests.
|
|
287
|
+
- `analyze()`: hourly buckets with sessions, prompts, decisions, context switches, active minutes, streak and late-night flag, scored 0–100, from real-format transcripts.
|
|
288
|
+
- CLI: `zapara week` and `zapara day` with `--json`, `--to`, `--days`, `--projects`; scans `~/.claude/projects`, skipping subagent transcripts and files older than the window.
|
|
289
|
+
- Week heatmap and day table with `--explain`; colors in a TTY, JSON in a pipe.
|
|
290
|
+
- Inbound messages from subagents, other sessions and background tasks are counted as `reports`, separate from human `prompts`; assistant output tokens are summed once per request as `outputTokens`. Both are measured and shown in the day table, week totals and JSON.
|
|
291
|
+
- `bun run stats`: per-hour signal distributions (n, p50, p75, p90, max, zero) over the active hours of a window, top 8 hours by reports and by human prompts, and a transcript-format drift line (records vs. events recognised by the parser), for comparing the same window across two machines before calibrating `src/score.ts`. Numbers only; never a file path or message text.
|
|
292
|
+
- `zapara card`: the last 14 days as one 2400×1260 picture (PNG, WebP, or the HTML page itself): one of four characters by dominant load, a sentence, the peak hour, the share of hours at each level, three highlights. Rendered locally by `Bun.WebView`; the page embeds its fonts and character sheet and references nothing. `--json` prints the card's data. The only command that writes a file.
|
|
293
|
+
- Published on npm as `@drakulavich/zapara`: `bunx @drakulavich/zapara@latest` runs it without a clone; releases publish from GitHub Actions with OIDC trusted publishing and provenance, no npm token.
|
|
294
|
+
|
|
295
|
+
### Changed
|
|
296
|
+
- Score weights are integer points of 100 so half-point sums round exactly; the index is the rounded sum of the unrounded weighted parts.
|
|
297
|
+
- Index calibrated on two machines × 14 days: parallel 25 (norm 4 sessions), pace 15 (norm 20 prompts/h), supervision 30 (3·decisions + reports + context switches, norm 45), reading 10 (norm 80k output tokens), streak 10, late night 10. `parts` in JSON and `--explain` are now six: `par pace sup read strk late`.
|
|
298
|
+
- Week footer: the legend drops the ranges and the "none" entry, the totals line drops its prefix and commas, and both are dimmed in a TTY; the level ranges are in `--help`; counts past 9 999 print compact (12k, 1.2M).
|
|
299
|
+
- Day table: an event column that is 0 in every row is left out, and one dimmed line names what the day had none of; the skeleton columns always show.
|
|
300
|
+
|
|
301
|
+
### Fixed
|
|
302
|
+
- A symlink loop or an unreadable directory anywhere under the projects root no longer aborts the scan as `projects directory not found`; that directory is skipped and every other transcript still counts. Symlinks are not followed.
|
|
303
|
+
- "1 session at once", "1 agent report", "1 prompt": the card sentence and the week footer use the singular for exactly one.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Anton Yakutovich
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
<h1 align="center">cogload</h1>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
|
|
5
|
+
<a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
|
|
6
|
+
<a href="https://www.npmjs.com/package/@drakulavich/cogload"><img src="https://img.shields.io/npm/v/@drakulavich/cogload?logo=npm&color=cb3837" alt="npm"></a>
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center"><b>How hard was today?</b> cogload reads the transcripts Claude Code already writes on your machine and scores every hour 0–100 from parallel sessions, prompt pace, agent supervision, model output, streak length and late-night work. Nothing leaves the machine, no message text is kept.</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<img src="https://raw.githubusercontent.com/drakulavich/cogload/main/assets/demo.webp" alt="cogload demo: week heatmap, day table, JSON" width="800">
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
Claude Code writes a JSONL transcript for every session under `~/.claude/projects`. cogload reads those files, puts each record in the local hour it happened in, and turns the hour into one number. A week is a heatmap of seven rows by 24 cells; a day is a table with one row per hour and, with `--explain`, the weighted contribution of each component.
|
|
16
|
+
|
|
17
|
+
## Quick start
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
# Skip this if you already have Bun 1.4.2 or newer
|
|
21
|
+
curl -fsSL https://bun.sh/install | bash
|
|
22
|
+
|
|
23
|
+
# Run it once, without installing
|
|
24
|
+
bunx @drakulavich/cogload@latest
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
To keep it, install it with Bun. The same command upgrades it later.
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
bun add -g @drakulavich/cogload
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Coming from zapara, run `bun remove -g @drakulavich/zapara` first: both packages claim the `zapara` command. cogload keeps that command until 1.0.0, and it prints one line on stderr saying it is now cogload. cogload starts over in `~/.claude/cogload/`, rebuilding its cache with one full scan; `~/.claude/zapara/` can be deleted once nothing runs zapara.
|
|
34
|
+
|
|
35
|
+
`cogload` lands in Bun's global bin directory, `~/.bun/bin` unless `BUN_INSTALL_BIN` says otherwise; `bun pm bin -g` prints the one in force. Bun's own installer puts that directory on your PATH; a Homebrew Bun does not, so add it yourself. Then:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
cogload # the last 7 days
|
|
39
|
+
cogload yesterday --explain # one day, with the components behind each index
|
|
40
|
+
cogload card # the picture
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
No build step and no runtime dependency: Bun runs `src/cli/index.ts` from the package as it is.
|
|
44
|
+
|
|
45
|
+
## What it looks like
|
|
46
|
+
|
|
47
|
+
The week below, and the day behind the fold under it, come from the synthetic fixture in `tests/fixtures/busy-week`: a calm morning of one session, a five-session storm in the middle of the day, and a late tail that runs past midnight.
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 peak active
|
|
51
|
+
Mon 14/09 · · · · · · · · · ░ ░ ░ █ █ █ · · · · · ░ ░ · ░ 87 8h50
|
|
52
|
+
Tue 15/09 · · · · · · · · · · ░ ░ ░ ░ ▒ ▒ ▒ ░ · · · · · · 33 7h55
|
|
53
|
+
Wed 16/09 · · · · · · · · · · · · · · · · · · · · · · · · - 0h00
|
|
54
|
+
Thu 17/09 · · · · · · · · · · · ░ ░ · · · · · · · · · · · 15 1h55
|
|
55
|
+
Fri 18/09 · · · · · · · · · · · · · · · ▓ · · · · · · · · 81 0h35
|
|
56
|
+
Sat 19/09 ░ ░ · · · · · · · · · · · · · · · · · · · · · · 25 1h55
|
|
57
|
+
Sun 20/09 · · · · · · · · · · · · · · · · · · · · · · · · - 0h00
|
|
58
|
+
|
|
59
|
+
░ calm ▒ warming ▓ heating █ fried
|
|
60
|
+
21h10 active 323 prompts 0 reports 86 decisions 5 sessions at once
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
<details>
|
|
64
|
+
<summary><b>Monday hour by hour, and the commands that print both</b></summary>
|
|
65
|
+
|
|
66
|
+
The fixture's timestamps are UTC and cogload buckets by local time, so pin the zone to get these exact hours:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
TZ=UTC bun src/cli/index.ts --projects tests/fixtures/busy-week --to 2026-09-20 --no-color
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
That prints the grid above. One day of it, with the weighted parts behind each index:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
TZ=UTC bun src/cli/index.ts 2026-09-14 --projects tests/fixtures/busy-week --explain --no-color
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
hour index level sess prompts intr rej quest plan mode ctx-sw streak out-tok par pace sup read strk late
|
|
80
|
+
09:00 15 Calm 1 6 0 0 0 0 0 0 50m 600 0 4.5 0 0.1 10 0
|
|
81
|
+
10:00 15 Calm 1 6 0 0 0 0 0 0 110m 600 0 4.5 0 0.1 10 0
|
|
82
|
+
11:00 15 Calm 1 7 0 0 0 0 0 0 179m 600 0 5.3 0 0.1 10 0
|
|
83
|
+
12:00 87 Fried 5 55 20 1 1 1 2 54 235m 55.0k 25 15 30 6.9 10 0
|
|
84
|
+
13:00 87 Fried 5 55 20 1 1 1 2 54 295m 55.0k 25 15 30 6.9 10 0
|
|
85
|
+
14:00 87 Fried 5 55 20 1 1 1 2 54 355m 55.0k 25 15 30 6.9 10 0
|
|
86
|
+
20:00 15 Calm 1 6 0 0 0 0 0 0 50m 600 0 4.5 0 0.1 10 0
|
|
87
|
+
21:00 15 Calm 1 6 0 0 0 0 0 0 110m 600 0 4.5 0 0.1 10 0
|
|
88
|
+
23:00 25 Calm 1 6 0 0 0 0 0 0 50m 600 0 4.5 0 0.1 10 10
|
|
89
|
+
no reports today
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The grid is a fixed 98 columns wide, its hour header included, and does not reflow, so it needs a terminal at least that wide.
|
|
93
|
+
|
|
94
|
+
</details>
|
|
95
|
+
|
|
96
|
+
## Share a card
|
|
97
|
+
|
|
98
|
+
`cogload card` turns your last two weeks into one picture: a character named after the kind of load that dominates your hours, the sentence behind it, the peak hour, the share of calm, warming, heating and fried hours, and up to three highlights. It carries no dates and no hour totals, so it does not read as a timesheet.
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
cogload card # writes cogload-card.png to ~/Downloads
|
|
102
|
+
cogload card --out card.webp # WebP instead; --out card.html writes the page itself
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
In a terminal it then asks `open it? [Y/n]`: Enter opens the picture in the default viewer, where ⌘C copies it for a chat. A pipe or a script is never asked.
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
The Marathoner: Longest streak 7h53m without a break, 68% of your hours calm.
|
|
109
|
+
wrote cogload-card.png to Downloads
|
|
110
|
+
open it? [Y/n]
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
<p align="center"><img src="https://raw.githubusercontent.com/drakulavich/cogload/main/assets/card.webp" alt="cogload card: The Marathoner, longest streak 7h53m, 68% of hours calm" width="800"></p>
|
|
114
|
+
|
|
115
|
+
This one comes from the same `busy-week` fixture as the pictures above. A headless browser that Bun drives takes the picture: WebKit on macOS, an installed Chromium browser (Chrome, Edge, Brave, Chromium) elsewhere. On Linux or Windows, install one or write `--out card.html` and open the page in any browser.
|
|
116
|
+
|
|
117
|
+
If your card told you something about your week, star [the repository](https://github.com/drakulavich/cogload) so other people can find cogload.
|
|
118
|
+
|
|
119
|
+
## Usage
|
|
120
|
+
|
|
121
|
+
| Command | What it does |
|
|
122
|
+
|---|---|
|
|
123
|
+
| `cogload` | The last 7 days ending today, one cell per hour, in local time. |
|
|
124
|
+
| `cogload --days 30` | The last 30 days. `--days` takes an integer from 1 to 90. |
|
|
125
|
+
| `cogload --from 2026-09-01 --to 2026-09-14` | Any window, both days inclusive, at most 90 days. `--to` alone is 7 days ending there, `--days 30 --to 2026-09-14` is 30 days ending there. |
|
|
126
|
+
| `cogload today` | Today, one row per hour that had activity. `yesterday` likewise. |
|
|
127
|
+
| `cogload 2026-09-14 --explain` | One day, with the six weighted components behind each index. |
|
|
128
|
+
| `cogload card` | The last 14 days as one shareable picture, `cogload-card.png` in `~/Downloads`. |
|
|
129
|
+
| `cogload card --days 30 --out me.webp` | Any window from 1 to 90 days; `.png`, `.webp` or `.html` by extension. `--json` prints the card's data instead. |
|
|
130
|
+
| `cogload status` | Writes today's load to `~/.claude/cogload/status.json` for a status line to read, and prints the same line. See [Status line](#status-line). |
|
|
131
|
+
|
|
132
|
+
| Flag | What it does |
|
|
133
|
+
|---|---|
|
|
134
|
+
| `--days <N>`, `--from <date>`, `--to <date>` | The window. A date is `YYYY-MM-DD`, `today` or `yesterday`. `--days=30` works as well as `--days 30`. |
|
|
135
|
+
| `--explain` | With a day: the six weighted parts behind each index. |
|
|
136
|
+
| `--json` | Print the whole window as one JSON document instead of a table. |
|
|
137
|
+
| `--projects <dir>` | Read this directory instead of `~/.claude/projects`. |
|
|
138
|
+
| `--out <path>` | Where `card` writes instead of `~/Downloads`; the extension picks the format. |
|
|
139
|
+
| `--no-color` | Plain glyphs and peaks with no ANSI codes. `NO_COLOR` in the environment does the same. |
|
|
140
|
+
| `--no-cache` | Read and parse every transcript again instead of using `~/.claude/cogload/cache.db`. |
|
|
141
|
+
| `--verbose` | After the output, prints to stderr where the time went: files scanned and read, megabytes, cache hits and misses (or `off` with `--no-cache`, or when the cache could not be opened or read, including an empty `HOME`), and milliseconds for each step in the order it ran: starting Bun and loading cogload, opening the cache, scanning, looking files up in the cache, reading the files it missed, analysis, saving to the cache, the card's render, and the status file's write. The rows add up to the total within a few milliseconds. It also prints the cogload and Bun versions, platform and CPU count. Numbers only, no path, so the lines are safe to paste into an issue when cogload is slow on your machine. |
|
|
142
|
+
| `-h`, `--help` | Usage, exit 0. |
|
|
143
|
+
| `-V`, `--version` | The version from `package.json`, exit 0. |
|
|
144
|
+
|
|
145
|
+
Levels: calm 0–29, warming 30–59, heating 60–84, fried 85–100.
|
|
146
|
+
|
|
147
|
+
The grid and the day print a text table when stdout is a terminal and JSON otherwise, so `cogload | cat` prints JSON; no flag forces text in a pipe yet. `card` and `status` write their file and print their lines whether piped or not. `card` asks to open the picture only when stdin and stdout are both a terminal, and never on Windows. While the browser engine draws a picture, a terminal's stderr shows `drawing the card…`, cleared before the result. `card --json` is the exception: it prints the card's data and writes no file, so `--out` with it is a usage error. `--json` changes nothing for `status`, whose line is already JSON and whose file is written either way.
|
|
148
|
+
|
|
149
|
+
A run that works exits 0, and so does a window with no data, which prints an empty grid. Exit 1 is a failure cogload can name, printed as one line to stderr that never contains a path: the projects directory missing or unreadable, `status` unable to write its file, `card` unable to write its picture or to find a browser engine, `card` without `--out` on a machine with no `~/Downloads` folder, `card` over a window with no activity (`card --json` prints `null` and exits 0 instead), and whatever else goes wrong below the command line. Exit 2 is a usage error, such as a bad date, an unknown flag or a value flag given twice; it prints one line and a hint to `--help`.
|
|
150
|
+
|
|
151
|
+
## Status line
|
|
152
|
+
|
|
153
|
+
A status line wants one number every thirty seconds and cannot wait half a second for a transcript scan, so cogload writes the number down and the status line reads it back. `cogload status` computes today exactly as `cogload today` does, writes it as one line of JSON to `~/.claude/cogload/status.json`, and prints the same line. Only `--projects`, `--no-cache` and `--verbose` apply, `--json` and `--no-color` change nothing, and the window flags, `--explain` and `--out` are usage errors. There is one file per user, whatever `--projects` said, created with mode `0600` in a directory with mode `0700`; the write goes to a temporary file and is renamed into place, so a reader sees the old line or the new one and never half of one. The file holds the nine values below and nothing else: no path, no project, no session count, no text.
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{"schema":1,"asOf":"2026-09-19T12:30:38.300Z","date":"2026-09-19","hour":15,"index":36,"level":"Warming","peak":41,"activeMin":555,"streakMin":166}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
| Field | Meaning |
|
|
160
|
+
|---|---|
|
|
161
|
+
| `schema` | The shape of this file: `1`. A reader that sees a number it does not know shows nothing. It changes only when a field changes meaning or goes away; adding a field does not bump it. A field that keeps its name, unit and range but is measured differently (the presence rule of 2026-09-19 for `activeMin` and `streakMin`) does not bump it either: a reader shows the corrected number, and the change is a CHANGELOG entry. |
|
|
162
|
+
| `asOf` | When the snapshot was taken, ISO 8601 UTC: the `Day.asOf` of the base spec, the `now` of this run. A reader decides staleness from this field, never from the file's mtime. |
|
|
163
|
+
| `date` | The local calendar day the numbers describe, `YYYY-MM-DD`. |
|
|
164
|
+
| `hour` | The local hour that contains `asOf`, `0`..`23`. |
|
|
165
|
+
| `index` | The load index of the sixty minutes ending at `asOf`, `0`..`100`, or `null` when they hold no session. It does not reset at an hour boundary: the hour buckets of `cogload today` are calendar hours, this one is the clock's last hour. |
|
|
166
|
+
| `level` | That index's level, `Calm`, `Warming`, `Heating` or `Fried`, or `null` with `index`. A reader colors by this field so it never needs the thresholds. |
|
|
167
|
+
| `peak` | The day's peak index so far, including the last sixty minutes, so it is never below `index`; `null` on a day with no activity. |
|
|
168
|
+
| `activeMin` | Minutes of your presence in the day so far: the 5-minute slots covered by your actions and the gaps of at most 10 minutes between them; `0` on a day with no action of yours. |
|
|
169
|
+
| `streakMin` | Minutes of your live presence streak as of `asOf`: from the streak's first action to `asOf`, when your last action is no more than 10 minutes before `asOf`; `0` once you have been away longer. It keeps growing while you sit there, and it does not reset at an hour boundary. |
|
|
170
|
+
|
|
171
|
+
Refreshing is the reader's job, and cogload adds no hook, no timer and no daemon. A reader that finds the file stale or missing starts `cogload status` detached and draws what it has, which is also how the file first comes to exist on a machine that never ran cogload. The rest of the contract, from strict decoding to concurrent runs, is in [the status file spec](docs/superpowers/specs/2026-09-19-zapara-status-file-design.md). The `cognitive-load` plugin below reads it another way: it runs `cogload status` itself, after every turn and once a minute, and reads the line it prints.
|
|
172
|
+
|
|
173
|
+
## Inside Claude Code
|
|
174
|
+
|
|
175
|
+
The `cognitive-load` plugin draws the same number above the Claude Code prompt:
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
▓ Heating 68 · peak 81 · streak 2h40 · active 6h15
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Install it from this repository's marketplace, in Claude Code:
|
|
182
|
+
|
|
183
|
+
```
|
|
184
|
+
/plugin marketplace add drakulavich/cogload
|
|
185
|
+
/plugin install cognitive-load@cogload
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Coming from the `zapara` marketplace, remove it first (`/plugin marketplace remove zapara`). The plugin's own store starts over with the new marketplace, so a rest in progress ends and `/overrides` lists nothing until the next override.
|
|
189
|
+
|
|
190
|
+
The plugin runs `cogload status` when a session starts and after every turn, and reads the load again every minute: from the reading another session of the plugin took less than a minute ago, or from a new run. So `cogload` has to be on the `PATH` Claude Code was started with; a Homebrew Bun leaves `~/.bun/bin` off it. The band is coloured by level, keeps only `▓ Heating 68` when it is under 50 columns wide, and is not drawn when the last sixty minutes are calm or hold no session. When a run fails, the band keeps the last good reading, or stays away if there is none, and the reason goes to Claude Code's debug log (`claude --debug`) as one of `not found`, `exit <code>`, `timeout` or `bad line`. The plugin is not part of the npm package; [its spec](docs/superpowers/specs/2026-10-03-zapara-cognitive-load-plugin-design.md) has the rest.
|
|
191
|
+
|
|
192
|
+
The plugin also makes you rest. When a reading shows a presence streak of 40 minutes or a Fried hour, it holds every prompt you send, typed, queued or from a link in the transcript, in every session that runs it, for ten minutes: `Rest until 14:32 (7 min). Start with "override: <reason>" to go on.` The rest can start while you read, and the band counts it down, `rest until 14:32 (7 min)`. Ten minutes without a prompt is the gap that ends a streak in cogload, so the next one starts at zero. A streak makes you rest once. A first line `override: <reason>`, the reason at least three words, lifts it until that streak ends and sends what follows it; the band then counts `overrides this week`, and `/overrides` lists the last 14 days with their reasons, for the week's review. Answers to Claude's questions, slash commands, a running turn, and prompts from notifications, other sessions or scheduled tasks are never held. [The rest's spec](docs/superpowers/specs/2026-10-04-zapara-forced-rest-design.md) has the details.
|
|
193
|
+
|
|
194
|
+
## Privacy
|
|
195
|
+
|
|
196
|
+
cogload reads `~/.claude/projects/**/*.jsonl`, skipping subagent transcripts under `subagents/`. It follows no symlink inside that directory, so a project directory that is a symlink is not read; `--projects` itself may be one. It picks files by modification time first, and opens one whose modification time is older than the window only to read the last timestamp in its final 64 KB; nothing from that tail is kept or printed. It compares message text against a few fixed markers, for interrupts, tool rejections and inbound agent messages, then discards it. What survives into an event is a timestamp, a session id, an event kind and a token count.
|
|
197
|
+
|
|
198
|
+
cogload keeps, writes and prints no message text, prompt length, file path or session title. The CLI never prints a path it derived or read, not even the projects root when it cannot open it. It sends nothing anywhere, installs nothing into Claude Code, and writes no file except the card, the status file and the cache below. The optional `cognitive-load` plugin runs `cogload status` and keeps the nine values of its line in the session's state; it reads no transcript or tool call and never keeps or logs what the command printed. It reads the prompts you type only to hold them during a rest and to find an `override:` line. Its own store, a JSON file under Claude Code's configuration directory, keeps when the current rest ends, when the last resting streak began, and the time and reason of each override for 14 days; the reason is the only text it keeps. While it draws a PNG or WebP, the card's page also sits in the temporary directory as a `0600` file, removed when the render ends.
|
|
199
|
+
|
|
200
|
+
Between runs, cogload caches each transcript's parsed events in `~/.claude/cogload/cache.db`. A hit still reads the last 4 KiB of the file to confirm it matches the cached row, then skips reading and parsing the rest. So a changed file is recognised by its size, modification time and last 4 KiB: an edit earlier in the file that keeps its size and modification time is not seen, and `--no-cache` parses everything again. A row is keyed by the transcript's device and inode, never by its path or a hash of it. Besides the device and inode, a row stores a fingerprint of the parser that wrote it, the file's size and modification time, a hash of its last 4 KiB, the cutoff its events were parsed with, when the row was last used, and the parsed events themselves. No message text, prompt length, path or title is stored. `--no-cache` runs without reading or writing it.
|
|
201
|
+
|
|
202
|
+
## Limits
|
|
203
|
+
|
|
204
|
+
- Time is local and buckets are whole hours, so an hour that straddles midnight or a daylight-saving change is bucketed by the local clock. On a fall-back day two wall-clock hours share one label and merge, so that bucket can hold up to 120 active minutes and the day up to 1500.
|
|
205
|
+
- cogload reads only Claude Code transcripts. Work in other tools, and time away from the keyboard, is invisible.
|
|
206
|
+
- A file whose modification time is older than the window is still read when the last timestamp in it falls inside the window, so a restored or synced transcript is not lost. A very old session touched today is read in full, but only its in-window events count.
|
|
207
|
+
- The transcript format is Claude Code's private format, built against version 2.1.274, and it may drift. `bun run stats` shows when it has.
|
|
208
|
+
- The norms come from two machines of one user working in auto mode, which makes them a starting point for a conversation about the metric rather than a study.
|
|
209
|
+
- The 98-column grid does not adapt to a narrow terminal.
|
|
210
|
+
- For the grid and the day a pipe always gets JSON, and there is no flag to ask for text instead.
|
|
211
|
+
- The card needs a browser engine: WebKit comes with macOS, elsewhere a Chromium browser (Chrome, Edge, Brave, Chromium) must be installed. `--out card.html` works everywhere.
|
|
212
|
+
- A window that includes today is a snapshot: today's entry in the JSON carries `asOf`, the tables end with `as of HH:MM`, and two runs minutes apart differ while Claude Code is still writing. Today's numbers cover everything up to `asOf` and nothing timestamped after it, even if it lands in the same run. `cogload status` writes that snapshot to a file for a status line.
|
|
213
|
+
|
|
214
|
+
## Under the hood
|
|
215
|
+
|
|
216
|
+
The formula behind the number and the transcript record behind every column, for when the number surprises you. For the whole path from a transcript line to the status line, with a diagram, read [How the numbers are made](docs/how-the-numbers-are-made.md).
|
|
217
|
+
|
|
218
|
+
<details>
|
|
219
|
+
<summary><b>How the index works</b></summary>
|
|
220
|
+
|
|
221
|
+
Every hour that had activity gets six components normalized into `[0, 1]` and summed with integer weights:
|
|
222
|
+
|
|
223
|
+
```
|
|
224
|
+
parallel = clamp((sessions - 1) / 4) # 1 session → 0, 3 → 0.5, 5+ → 1
|
|
225
|
+
pace = clamp(prompts / 20) # 10 prompts/hour → 0.5, 20+ → 1
|
|
226
|
+
supervision = clamp((3 * decisions + reports + contextSwitches) / 45) # 15 decisions alone → 1; 45 reports alone → 1
|
|
227
|
+
reading = clamp(outputTokens / 80000) # 40k → 0.5, 80k+ → 1
|
|
228
|
+
streak = clamp(streakMin / 40) # 20 min → 0.5, 40+ → 1
|
|
229
|
+
late = lateNight ? 1 : 0
|
|
230
|
+
|
|
231
|
+
index = round(25*parallel + 15*pace + 30*supervision + 10*reading + 10*streak + 10*late)
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
`decisions` is the sum of interrupts, tool rejections, questions, plan reviews and permission-mode switches. Without the late-night flag the index tops out at 90. An hour with no activity has no index at all: it renders as `·` and is `null` in JSON.
|
|
235
|
+
|
|
236
|
+
| Level | Range |
|
|
237
|
+
|---|---|
|
|
238
|
+
| Calm | 0–29 |
|
|
239
|
+
| Warming | 30–59 |
|
|
240
|
+
| Heating | 60–84 |
|
|
241
|
+
| Fried | 85–100 |
|
|
242
|
+
|
|
243
|
+
The norms are the p90 of two weeks of real transcripts on two machines, 116 and 114 active hours. Why each one is what it is, and what surprised me in that data, is in [How the numbers are made](docs/how-the-numbers-are-made.md#5-the-index).
|
|
244
|
+
|
|
245
|
+
Weights and norms live in one exported constant in `src/lib/metrics/score.ts`, so a recalibration is one diff there plus a line in `CHANGELOG.md`.
|
|
246
|
+
|
|
247
|
+
</details>
|
|
248
|
+
|
|
249
|
+
<details>
|
|
250
|
+
<summary><b>What each column of the day table counts</b></summary>
|
|
251
|
+
|
|
252
|
+
| Column | What it counts |
|
|
253
|
+
|---|---|
|
|
254
|
+
| `sess` | Distinct session ids with at least one user or assistant record in the hour. |
|
|
255
|
+
| `prompts` | Messages the human typed. A `user` record whose text is neither an interrupt marker nor an agent-message marker; `isMeta`, sidechain, `claude -p` and Agent SDK records are excluded. |
|
|
256
|
+
| `rep` | Inbound messages from subagents, other sessions and background tasks. A `user` record whose text starts with one of the agent-message markers, which is something to read and react to rather than something typed. |
|
|
257
|
+
| `intr` | Interrupts. A `user` record whose text block starts with `[Request interrupted by user`, covering both the plain and the tool-use form. |
|
|
258
|
+
| `rej` | Tool rejections. A `tool_result` block saying the user did not want to proceed with that tool use. |
|
|
259
|
+
| `quest` | `AskUserQuestion` tool calls in an assistant message, one per block. |
|
|
260
|
+
| `plan` | `ExitPlanMode` tool calls in an assistant message, one per block. |
|
|
261
|
+
| `mode` | Permission-mode switches. A `permission-mode` record whose mode differs from the previous one; the first record of a session sets the baseline and repeats of the same mode count nothing. |
|
|
262
|
+
| `ctx-sw` | Context switches. Over the hour's prompts in time order, the number of consecutive pairs that came from different sessions. |
|
|
263
|
+
| `streak` | Minutes of the longest presence streak the hour saw. Presence is every action you take: a prompt, an interrupt, a tool rejection, an answer to a question or a plan. A streak is a run of them no more than 10 minutes apart, across sessions, and it may reach back before the hour. Agent activity between two of your actions does not bridge a gap. |
|
|
264
|
+
| `out-tok` | Assistant output tokens, summed once per request and only for requests that produced a text block. Claude Code repeats the same usage on each content block of a response, and a request holding only tool calls is not text anyone reads. |
|
|
265
|
+
|
|
266
|
+
`bun run stats --days 14` is the tool the norms were set with. It prints the per-hour distribution of each signal over the active hours of a window (n, p50, p75, p90, max, and how many hours were zero), the top hours by reports and by human prompts, and a format-drift line comparing records seen against events the parser recognised. Run it on another machine, or after a Claude Code update, to see whether the norms and the parser still fit. It prints numbers and nothing else.
|
|
267
|
+
|
|
268
|
+
</details>
|
|
269
|
+
|
|
270
|
+
## Development
|
|
271
|
+
|
|
272
|
+
```bash
|
|
273
|
+
git clone git@github.com:drakulavich/cogload.git
|
|
274
|
+
cd cogload
|
|
275
|
+
bun install
|
|
276
|
+
bun link
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
`bun link` registers the clone's `bin` entry, so `cogload` runs this checkout; without it, `bun src/cli/index.ts` does the same thing.
|
|
280
|
+
|
|
281
|
+
```bash
|
|
282
|
+
bun run check # tsc --noEmit, then the test suite under TZ=UTC
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Tests are fixture-driven: they build or load transcripts in the real Claude Code format and assert the statistics that come out of the public seams, `analyze()`, `report()` and the CLI itself. No test imports the parser, the deriver or the scanner, so refactoring internals never touches a test. The rules every change follows are in [CLAUDE.md](CLAUDE.md), the design is in [docs/superpowers/specs/2026-09-17-zapara-design.md](docs/superpowers/specs/2026-09-17-zapara-design.md), and every change is recorded in [CHANGELOG.md](CHANGELOG.md).
|
|
286
|
+
|
|
287
|
+
## Where it comes from
|
|
288
|
+
|
|
289
|
+
The question comes from Addy Osmani's [Your parallel Agent limit](https://addyosmani.com/blog/cognitive-parallel-agents/). More agents running does not make more of you available, because "your cognitive bandwidth doesn't parallelize", and the cost of the ones you are not looking at is what he calls the ambient anxiety tax: "the part of your mind that can't fully relax because it knows something might be silently going sideways in a thread you haven't checked in twenty minutes." His own ceiling is "somewhere around three to four threads depending on complexity", and his advice is to start with one thread less than feels right.
|
|
290
|
+
|
|
291
|
+
The index was calibrated before I read that, from the 90th percentile of two weeks on two machines, and it arrived at the same number: `NORMS.parallelSpan` in [src/lib/metrics/score.ts](src/lib/metrics/score.ts) is 4, so the fifth session running at once spends all 25 points for parallel work.
|
|
292
|
+
|
|
293
|
+
The post and this tool disagree about what to watch. Osmani's signal is the quality of your own review: you have passed your ceiling when your confidence in what you are accepting starts dropping. A transcript cannot see that. It can see how much model output went past you, which is the `out-tok` column and ten of the hundred points, and it can see the shape of the hour around it. The index is a proxy with a known blind spot, and the number is worth something only next to your memory of the hour it scores.
|
|
294
|
+
|
|
295
|
+
Most of the advice in this area stops at fewer threads, smaller scope and more breaks, with few numbers you can hold yourself to. An hour with a score on it is at least something you can disagree with.
|
|
296
|
+
|
|
297
|
+
Until 0.10.0 the tool was called zapara, Russian slang for a crunch, which told an English reader nothing.
|
|
298
|
+
|
|
299
|
+
---
|
|
300
|
+
|
|
301
|
+
<p align="center">Made with ❤️ and 🥤 energy under <a href="LICENSE">MIT License</a></p>
|
|
Binary file
|