@drakulavich/cogload 0.10.0 → 0.11.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 +33 -0
- package/README.md +16 -27
- package/package.json +2 -2
- package/src/lib/text/render.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,39 @@ All notable changes to this project are documented here. The format follows
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [0.11.0] - 2026-10-05
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- `/cogload` in the `cognitive-load` plugin says what drives the hour's load,
|
|
12
|
+
in counts: `Heating 80 this hour, at the cap: 16 decisions and 13 context
|
|
13
|
+
switches, 32 prompts, a 57m streak.`, then the week's rests and overrides
|
|
14
|
+
with the newest reason. It replaces `/overrides`, and the plugin now keeps
|
|
15
|
+
overrides 7 days instead of 14.
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
- The `cognitive-load` band draws Calm and Warming in Claude Code's theme
|
|
19
|
+
colours `success` and `warning`, which stay readable on a light theme,
|
|
20
|
+
instead of plain green and yellow.
|
|
21
|
+
- The `cognitive-load` band no longer counts the week's overrides; `/cogload`
|
|
22
|
+
does.
|
|
23
|
+
- The `cognitive-load` band starts with a dot in the level's colour,
|
|
24
|
+
`● Heating`, in the terminal and the Desktop Code tab, whose proportional
|
|
25
|
+
font drew `▓` as a dotted block.
|
|
26
|
+
- The `cognitive-load` band shows the level and the streak,
|
|
27
|
+
`● Heating · streak 20m`; the index, peak and active time stay in
|
|
28
|
+
`cogload`. The plugin greets a new install with one toast, says once when
|
|
29
|
+
`cogload` is not on Claude Code's `PATH`, and answers an override with
|
|
30
|
+
a reason under three words with
|
|
31
|
+
`An override needs a reason of three words or more.`
|
|
32
|
+
- The `cognitive-load` band warns before a rest: from a 35-minute streak it
|
|
33
|
+
says `rest in 5 min` and counts down. A held prompt says
|
|
34
|
+
`Rest until 14:32. Your prompt is saved.` (from Remote
|
|
35
|
+
Control, `Rest until 14:32.`), and only the first one after install says how to
|
|
36
|
+
override.
|
|
37
|
+
- The `cognitive-load` band colours only the level, `● Heating`, and
|
|
38
|
+
dims the rest of the line. Heating is orange in the band and in the CLI's
|
|
39
|
+
week grid and legend.
|
|
40
|
+
|
|
8
41
|
## [0.10.0] - 2026-10-05
|
|
9
42
|
|
|
10
43
|
### Added
|
package/README.md
CHANGED
|
@@ -127,7 +127,7 @@ If your card told you something about your week, star [the repository](https://g
|
|
|
127
127
|
| `cogload 2026-09-14 --explain` | One day, with the six weighted components behind each index. |
|
|
128
128
|
| `cogload card` | The last 14 days as one shareable picture, `cogload-card.png` in `~/Downloads`. |
|
|
129
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.
|
|
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
131
|
|
|
132
132
|
| Flag | What it does |
|
|
133
133
|
|---|---|
|
|
@@ -148,36 +148,25 @@ The grid and the day print a text table when stdout is a terminal and JSON other
|
|
|
148
148
|
|
|
149
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
150
|
|
|
151
|
-
##
|
|
151
|
+
## Inside Claude Code
|
|
152
152
|
|
|
153
|
-
|
|
153
|
+
The `cognitive-load` plugin draws the level of the last hour and your current streak above the Claude Code prompt:
|
|
154
154
|
|
|
155
|
-
```
|
|
156
|
-
|
|
155
|
+
```
|
|
156
|
+
● Heating · streak 20m
|
|
157
157
|
```
|
|
158
158
|
|
|
159
|
-
|
|
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:
|
|
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:
|
|
176
160
|
|
|
177
161
|
```
|
|
178
|
-
|
|
162
|
+
Heating 80 this hour, at the cap: 16 decisions and 13 context switches, 32 prompts, a 57m streak.
|
|
163
|
+
This week: 2 rests, 1 override ("prod is down, fixing it").
|
|
179
164
|
```
|
|
180
165
|
|
|
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. Without `cogload` on the `PATH` 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, `cognitive-load shows your load above the prompt when it rises above Calm.`
|
|
169
|
+
|
|
181
170
|
Install it from this repository's marketplace, in Claude Code:
|
|
182
171
|
|
|
183
172
|
```
|
|
@@ -185,17 +174,17 @@ Install it from this repository's marketplace, in Claude Code:
|
|
|
185
174
|
/plugin install cognitive-load@cogload
|
|
186
175
|
```
|
|
187
176
|
|
|
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
|
|
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.
|
|
189
178
|
|
|
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
|
|
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. So `cogload` has to be on the `PATH` Claude Code was started with; a Homebrew Bun leaves `~/.bun/bin` off it. The first time the run cannot start, a toast says `cognitive-load needs cogload 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 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
180
|
|
|
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
|
|
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.
|
|
193
182
|
|
|
194
183
|
## Privacy
|
|
195
184
|
|
|
196
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.
|
|
197
186
|
|
|
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
|
|
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.
|
|
199
188
|
|
|
200
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.
|
|
201
190
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@drakulavich/cogload",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.11.0",
|
|
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",
|
|
7
7
|
"repository": { "type": "git", "url": "git+https://github.com/drakulavich/cogload.git" },
|
package/src/lib/text/render.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { levelOf } from "../metrics/index.ts";
|
|
|
3
3
|
import type { Day, HourBucket, Level } from "../types.ts";
|
|
4
4
|
|
|
5
5
|
const GLYPH: Record<Level, string> = { Calm: "░", Warming: "▒", Heating: "▓", Fried: "█" };
|
|
6
|
-
const ANSI: Record<Level, string> = { Calm: "32", Warming: "33", Heating: "
|
|
6
|
+
const ANSI: Record<Level, string> = { Calm: "32", Warming: "33", Heating: "38;5;208", Fried: "31" };
|
|
7
7
|
const LEVEL_NAME: Record<Level, string> = { Calm: "calm", Warming: "warming", Heating: "heating", Fried: "fried" };
|
|
8
8
|
const LEVELS: Level[] = ["Calm", "Warming", "Heating", "Fried"];
|
|
9
9
|
const WEEKDAY = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
|