@drakulavich/cogload 0.12.0 → 0.12.1

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 CHANGED
@@ -5,6 +5,17 @@ All notable changes to this project are documented here. The format follows
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [0.12.1] - 2026-10-06
9
+
10
+ ### Fixed
11
+ - A reader that closes the pipe early (`cogload | head -1`) no longer gets a
12
+ stack trace on stderr, and cogload exits 0.
13
+
14
+ ### Changed
15
+ - The README is a short page for a newcomer: install in one block an agent
16
+ can run, the week, the card, the plugin and privacy in brief. Every command,
17
+ flag and rule moved verbatim to `docs/reference.md`.
18
+
8
19
  ## [0.12.0] - 2026-10-06
9
20
 
10
21
  ### Fixed
package/README.md CHANGED
@@ -9,30 +9,30 @@
9
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
10
 
11
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">
12
+ <img src="https://raw.githubusercontent.com/drakulavich/cogload/main/assets/plugin.webp" alt="The cognitive-load plugin in Claude Code: a rest holds a prompt, an override lifts it, /cogload names what drives the hour" width="800">
13
13
  </p>
14
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.
15
+ ## Install
16
16
 
17
- ## Quick start
17
+ Run these in a terminal, or paste this repository's link into Claude Code and ask it to install cogload.
18
+
19
+ > **For an AI agent installing cogload:** run the block below top to bottom, skipping the Bun step if `bun --version` prints 1.4.2 or newer. Each command is safe to rerun. Then ask the user to restart Claude Code so the plugin loads.
18
20
 
19
21
  ```bash
20
- # Skip this if you already have Bun 1.4.2 or newer
22
+ # Bun 1.4.2 or newer; skip if `bun --version` already prints one
21
23
  curl -fsSL https://bun.sh/install | bash
24
+ export PATH="$HOME/.bun/bin:$PATH"
22
25
 
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
26
+ # The CLI; the same command upgrades it
30
27
  bun add -g @drakulavich/cogload
31
- ```
28
+ cogload --version
32
29
 
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.
30
+ # The cognitive-load plugin for Claude Code
31
+ claude plugin marketplace add drakulavich/cogload
32
+ claude plugin install cognitive-load@cogload
33
+ ```
34
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:
35
+ Restart Claude Code to load the plugin. With a Homebrew Bun, put `~/.bun/bin` on your `PATH` yourself. To try the CLI without installing it, run `bunx @drakulavich/cogload@latest`.
36
36
 
37
37
  ```bash
38
38
  cogload # the last 7 days
@@ -40,11 +40,9 @@ cogload yesterday --explain # one day, with the components behind each index
40
40
  cogload card # the picture
41
41
  ```
42
42
 
43
- No build step and no runtime dependency: Bun runs `src/cli/index.ts` from the package as it is.
44
-
45
43
  ## What it looks like
46
44
 
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.
45
+ A week 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
46
 
49
47
  ```
50
48
  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
@@ -60,38 +58,7 @@ Sun 20/09 · · · · · · · · · · · · · · · · ·
60
58
  21h10 active 323 prompts 0 reports 86 decisions 5 sessions at once
61
59
  ```
62
60
 
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>
61
+ Levels: calm 0–29, warming 30–59, heating 60–84, fried 85–100.
95
62
 
96
63
  ## Share a card
97
64
 
@@ -102,188 +69,36 @@ cogload card # writes cogload-card.png to ~/Downloads
102
69
  cogload card --out card.webp # WebP instead; --out card.html writes the page itself
103
70
  ```
104
71
 
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
72
  <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
73
 
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.
74
+ macOS draws it with WebKit; elsewhere it needs an installed Chromium browser, or write `--out card.html` and open the page in any browser.
116
75
 
117
76
  If your card told you something about your week, star [the repository](https://github.com/drakulavich/cogload) so other people can find cogload.
118
77
 
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. The file's fields are in [the status file spec](docs/superpowers/specs/2026-09-19-zapara-status-file-design.md), written when cogload was zapara and kept its files in `~/.claude/zapara/`. |
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, or `no activity on <date>` for one day. 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
78
  ## Inside Claude Code
152
79
 
153
- The `cognitive-load` plugin draws the level of the last hour and your current streak above the Claude Code prompt:
80
+ The `cognitive-load` plugin draws the last hour's level and your streak above the prompt, and `/cogload` says what drives it:
154
81
 
155
82
  ```
156
83
  ● Heating · streak 20m
157
84
  ```
158
85
 
159
- When the band turns Heating and you want to know why, type `/cogload`. It runs `cogload today --json` and names what drives the last sixty minutes in counts:
160
-
161
86
  ```
162
87
  Heating 80 this hour, at the cap: 16 decisions and 13 context switches, 32 prompts, a 57m streak.
163
88
  This week: 2 rests, 1 override ("prod is down, fixing it").
164
89
  ```
165
90
 
166
- The first line names every part of the score at its cap, heaviest weight first, or, with none at its cap, the one closest to it: `Warming 45 this hour, mostly 3 sessions at once.` With no scored hour it says `Nothing scored this hour.` The second line counts the rests and overrides of the last seven days and quotes the newest override's reason; with neither, it is left out. When `cogload` cannot start it prints the missing-`cogload` text below, and any other failure prints `cogload gave no reading.`
167
-
168
- The index, the day's peak and the active time stay in `cogload` in a terminal. The first session after install shows one toast, `Keep your head cold. The dot above the prompt shows how hot this hour runs.`
169
-
170
- Install it from this repository's marketplace, in Claude Code:
171
-
172
- ```
173
- /plugin marketplace add drakulavich/cogload
174
- /plugin install cognitive-load@cogload
175
- ```
176
-
177
- 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 the week's counts in `/cogload` start over.
178
-
179
- 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. It starts `cogload` from the `PATH` Claude Code was started with, and when that fails, `~/.bun/bin/cogload`: a Homebrew Bun, or the Desktop app opened from the Dock, can leave that directory off the `PATH`. The first time neither can start, a toast says `cogload is not on Claude Code's PATH: bun add -g @drakulavich/cogload`, once per install. The band starts with a dot in the level's colour, leaves out a zero streak, keeps only `● Heating` when it is under 50 columns wide, and is not drawn when the last sixty minutes 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.
180
-
181
- 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. From the 35th minute of a streak that would start a rest, the band warns in place of the streak, `● Heating · rest in 5 min`, and counts down each minute. A held prompt you typed goes back into the box with `Rest until 14:32. Your prompt is saved.`; one from Remote Control gets `Rest until 14:32.` The first held prompt after install also adds `To go on now, start the prompt with "override: <reason>".` 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. A shorter reason, or none, gets `An override needs a reason of three words or more.`, and a typed prompt goes back into the box as a held one does. The band does not count overrides; `/cogload` counts the week's and quotes the newest reason. 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.
91
+ It also makes you rest. After 40 minutes of work without a ten-minute gap, or in a Fried hour, it holds your prompts for ten minutes. A first line `override: <reason>`, the reason three words or more, lets you go on.
182
92
 
183
93
  ## Privacy
184
94
 
185
- 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.
186
-
187
- 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; `/cogload` runs `cogload today --json` and prints only counts from it. The plugin reads no transcript or tool call and never keeps or logs what a 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, the start of each rest for 7 days, whether it has shown the override hint, the welcome and the missing-`cogload` toast (`taught`, `welcomed`, `missingShown`), and the time and reason of each override for 7 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 or is interrupted. A process killed outright (`kill -9`) leaves it there until the system clears the temporary directory.
188
-
189
- 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.
190
-
191
- ## Limits
192
-
193
- - 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.
194
- - cogload reads only Claude Code transcripts. Work in other tools, and time away from the keyboard, is invisible.
195
- - 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.
196
- - 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.
197
- - 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.
198
- - The 98-column grid does not adapt to a narrow terminal.
199
- - For the grid and the day a pipe always gets JSON, and there is no flag to ask for text instead.
200
- - 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.
201
- - 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.
202
-
203
- ## Under the hood
204
-
205
- 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).
206
-
207
- <details>
208
- <summary><b>How the index works</b></summary>
209
-
210
- Every hour that had activity gets six components normalized into `[0, 1]` and summed with integer weights:
211
-
212
- ```
213
- parallel = clamp((sessions - 1) / 4) # 1 session → 0, 3 → 0.5, 5+ → 1
214
- pace = clamp(prompts / 20) # 10 prompts/hour → 0.5, 20+ → 1
215
- supervision = clamp((3 * decisions + reports + contextSwitches) / 45) # 15 decisions alone → 1; 45 reports alone → 1
216
- reading = clamp(outputTokens / 80000) # 40k → 0.5, 80k+ → 1
217
- streak = clamp(streakMin / 40) # 20 min → 0.5, 40+ → 1
218
- late = lateNight ? 1 : 0
219
-
220
- index = round(25*parallel + 15*pace + 30*supervision + 10*reading + 10*streak + 10*late)
221
- ```
222
-
223
- `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.
224
-
225
- | Level | Range |
226
- |---|---|
227
- | Calm | 0–29 |
228
- | Warming | 30–59 |
229
- | Heating | 60–84 |
230
- | Fried | 85–100 |
231
-
232
- 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).
233
-
234
- 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`.
235
-
236
- </details>
237
-
238
- <details>
239
- <summary><b>What each column of the day table counts</b></summary>
240
-
241
- | Column | What it counts |
242
- |---|---|
243
- | `sess` | Distinct session ids with at least one user or assistant record in the hour. |
244
- | `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. |
245
- | `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. |
246
- | `intr` | Interrupts. A `user` record whose text block starts with `[Request interrupted by user`, covering both the plain and the tool-use form. |
247
- | `rej` | Tool rejections. A `tool_result` block saying the user did not want to proceed with that tool use. |
248
- | `quest` | `AskUserQuestion` tool calls in an assistant message, one per block. |
249
- | `plan` | `ExitPlanMode` tool calls in an assistant message, one per block. |
250
- | `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. |
251
- | `ctx-sw` | Context switches. Over the hour's prompts in time order, the number of consecutive pairs that came from different sessions. |
252
- | `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. |
253
- | `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. |
254
-
255
- `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.
256
-
257
- </details>
258
-
259
- ## Development
260
-
261
- ```bash
262
- git clone git@github.com:drakulavich/cogload.git
263
- cd cogload
264
- bun install
265
- bun link
266
- ```
267
-
268
- `bun link` registers the clone's `bin` entry, so `cogload` runs this checkout; without it, `bun src/cli/index.ts` does the same thing.
269
-
270
- ```bash
271
- bun run check # tsc --noEmit, then the test suite under TZ=UTC
272
- ```
273
-
274
- 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).
275
-
276
- ## Where it comes from
277
-
278
- 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.
279
-
280
- 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.
281
-
282
- 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.
95
+ cogload reads `~/.claude/projects` on your machine and sends nothing anywhere. It keeps, writes and prints no message text, prompt length, file path or session title: what survives from a transcript is timestamps, session ids, event kinds and token counts. The plugin keeps one piece of text, the reason you give for an override. [The reference](docs/reference.md#privacy) lists every file cogload and the plugin write.
283
96
 
284
- 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.
97
+ ## More
285
98
 
286
- Until 0.10.0 the tool was called zapara, Russian slang for a crunch, which told an English reader nothing.
99
+ - [Reference](docs/reference.md): every command and flag, exit codes, the plugin and its rest in full, privacy and the cache, limits, the formula and what each column counts, development, and where cogload comes from.
100
+ - [How the numbers are made](docs/how-the-numbers-are-made.md): the path from a transcript line to the status line.
101
+ - [Changelog](CHANGELOG.md).
287
102
 
288
103
  ---
289
104
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@drakulavich/cogload",
3
- "version": "0.12.0",
3
+ "version": "0.12.1",
4
4
  "description": "Keep your head cold. A thermometer for your Claude Code days: every hour scored 0 to 100 from the transcripts already on your disk. Nothing leaves your machine.",
5
5
  "license": "MIT",
6
6
  "author": "Anton Yakutovich",
package/src/cli/index.ts CHANGED
@@ -42,6 +42,10 @@ async function main(): Promise<number> {
42
42
  }
43
43
 
44
44
  export function start(): void {
45
+ process.stdout.on("error", (e: NodeJS.ErrnoException) => {
46
+ if (e.code === "EPIPE") process.exit(0);
47
+ throw e;
48
+ });
45
49
  // exitCode, not exit(): exit() drops output still queued for a pipe.
46
50
  main().then((code) => { process.exitCode = code; }, (e: unknown) => {
47
51
  if (e instanceof HelpRequested) { console.log(USAGE); process.exit(0); }