@drakulavich/cogload 0.12.3 → 0.13.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 +40 -0
- package/README.md +13 -3
- package/package.json +1 -1
- package/src/cli/commands.io.ts +1 -1
- package/src/lib/metrics/derive.ts +30 -7
- package/src/lib/metrics/index.ts +1 -1
- package/src/lib/metrics/score.ts +18 -4
- package/src/lib/status/status.ts +10 -10
- package/src/lib/types.ts +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,46 @@ All notable changes to this project are documented here. The format follows
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [0.13.1] - 2026-10-10
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- After a `skip:` sent alone, the prompts the rest held come back into the
|
|
12
|
+
box. (#208)
|
|
13
|
+
|
|
14
|
+
### Changed
|
|
15
|
+
- A held prompt's hint says it is back in the box and to add
|
|
16
|
+
`skip: <reason>` as its last line. (#204)
|
|
17
|
+
- During a rest, a prompt from your phone goes through, and Claude's reply
|
|
18
|
+
begins by saying it went past the rest; typed prompts are still held. (#205)
|
|
19
|
+
|
|
20
|
+
### Fixed
|
|
21
|
+
- After twenty minutes away, `/cogload` says you have been away instead of
|
|
22
|
+
naming a part of a zero score. (#196)
|
|
23
|
+
- During a rest, a held prompt goes back into the box once instead of
|
|
24
|
+
doubling on every Enter. (#201)
|
|
25
|
+
- A `skip:` sent alone no longer comes back into the box after it lifts the
|
|
26
|
+
rest. (#206)
|
|
27
|
+
|
|
28
|
+
## [0.13.0] - 2026-10-09
|
|
29
|
+
|
|
30
|
+
### Added
|
|
31
|
+
- `status` writes `restAt`, when the running streak reaches 40 minutes, and
|
|
32
|
+
`restMin`, how long a rest must be to end it. (#192)
|
|
33
|
+
- Each score names the parts at their cap (`capped`) and the one closest to
|
|
34
|
+
it (`top`). (#192)
|
|
35
|
+
|
|
36
|
+
### Changed
|
|
37
|
+
- The live index counts the streak running now and cools after a break:
|
|
38
|
+
10 minutes away keep about half of the load from before, 20 minutes keep
|
|
39
|
+
none. (#192)
|
|
40
|
+
- The `cognitive-load` plugin 0.10.0 takes every number from cogload, so the
|
|
41
|
+
band, `/cogload` and the rest no longer disagree. It needs cogload 0.13.0
|
|
42
|
+
and says so once if an older one is installed. (#192)
|
|
43
|
+
|
|
44
|
+
### Fixed
|
|
45
|
+
- Right after a rest, `/cogload` no longer says a short streak is at the
|
|
46
|
+
cap. (#187)
|
|
47
|
+
|
|
8
48
|
## [0.12.3] - 2026-10-07
|
|
9
49
|
|
|
10
50
|
### Changed
|
package/README.md
CHANGED
|
@@ -8,6 +8,18 @@
|
|
|
8
8
|
|
|
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
|
+
## See your last two weeks
|
|
12
|
+
|
|
13
|
+
One command draws your last 14 days from the transcripts already on your disk, with nothing installed but [Bun](https://bun.sh) 1.4.2 or newer:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
bunx @drakulavich/cogload@latest card
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
<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>
|
|
20
|
+
|
|
21
|
+
No Bun yet: `curl -fsSL https://bun.sh/install | bash` first. macOS draws the card with WebKit; elsewhere it needs an installed Chromium browser.
|
|
22
|
+
|
|
11
23
|
<p align="center">
|
|
12
24
|
<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, a skip lifts it, /cogload names what drives the hour" width="800">
|
|
13
25
|
</p>
|
|
@@ -69,8 +81,6 @@ cogload card # writes cogload-card.png to ~/Downloads
|
|
|
69
81
|
cogload card --out card.webp # WebP instead; --out card.html writes the page itself
|
|
70
82
|
```
|
|
71
83
|
|
|
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>
|
|
73
|
-
|
|
74
84
|
macOS draws it with WebKit; elsewhere it needs an installed Chromium browser, or write `--out card.html` and open the page in any browser.
|
|
75
85
|
|
|
76
86
|
If your card told you something about your week, star [the repository](https://github.com/drakulavich/cogload) so other people can find cogload.
|
|
@@ -88,7 +98,7 @@ Heating 80 this hour, at the cap: 16 decisions and 13 context switches, 32 promp
|
|
|
88
98
|
This week: 1 rest taken, 1 skipped (last: "prod is down, fixing it").
|
|
89
99
|
```
|
|
90
100
|
|
|
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. Each held prompt gets the next short idea for the break, the minutes left and the way out: `Stand up and stretch. 7 min left
|
|
101
|
+
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. Each held prompt gets the next short idea for the break, the minutes left and the way out: `Stand up and stretch. 7 min left. Your prompt is back in the box: to send it, add "skip: <reason>" as its last line.` A `skip: <reason>` line at the start or the end of the prompt, the reason three words or more, lifts the rest.
|
|
92
102
|
|
|
93
103
|
## Privacy
|
|
94
104
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@drakulavich/cogload",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.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/commands.io.ts
CHANGED
|
@@ -10,7 +10,7 @@ import type { Day } from "../lib/types.ts";
|
|
|
10
10
|
import type { Args } from "./args.ts";
|
|
11
11
|
|
|
12
12
|
export async function table(a: Args, now: Date, cache: TranscriptCache | null, timing?: Timing): Promise<number> {
|
|
13
|
-
const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now }, timing, cache);
|
|
13
|
+
const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now, streakFrom: streakFrom(now) }, timing, cache);
|
|
14
14
|
const data = a.command === "day" ? days[0] : days;
|
|
15
15
|
const text = a.json ? renderJson(data!) : a.command === "day" ? renderDay(days[0]!, { explain: a.explain, color: a.color }) : renderWeek(days, a.color);
|
|
16
16
|
// Not console.log: in Bun 1.4.2, once process.stdout is touched (isTTY in parseArgs), console.log into a pipe stops at 64 KiB.
|
|
@@ -1,10 +1,13 @@
|
|
|
1
|
-
import { score } from "./score.ts";
|
|
2
|
-
import type { Day, Event, EventKind, HourBucket, LiveBucket, Metrics, Totals, Window } from "../types.ts";
|
|
1
|
+
import { fractionsOf, NORMS, score, scoreOf } from "./score.ts";
|
|
2
|
+
import type { Day, Event, EventKind, HourBucket, LiveBucket, Metrics, Part, Totals, Window } from "../types.ts";
|
|
3
3
|
|
|
4
4
|
const LOOKBACK_MS = 3 * 60 * 60 * 1000;
|
|
5
5
|
export const GAP_MS = 10 * 60 * 1000;
|
|
6
6
|
const SLOT_MS = 5 * 60 * 1000;
|
|
7
7
|
const LIVE_MS = 60 * 60 * 1000;
|
|
8
|
+
// The reader contract's ceiling for activeMin and streakMin (status file spec):
|
|
9
|
+
// a reader treats a larger value as no data, so a longer streak is written as this.
|
|
10
|
+
export const MAX_STREAK_MIN = 1500;
|
|
8
11
|
const LATE_HOURS = new Set([23, 0, 1, 2, 3, 4, 5]);
|
|
9
12
|
|
|
10
13
|
// Not localeCompare: a result must not depend on the locale.
|
|
@@ -83,11 +86,11 @@ function accumulate(a: Acc, e: Event, streakStart: number): void {
|
|
|
83
86
|
|
|
84
87
|
// `lateNight` is the caller's: an hour's own label, or the hour of `now` for the
|
|
85
88
|
// live bucket. A fresh accumulator is an empty hour and scores null.
|
|
86
|
-
function finish(a: Acc, lateNight: boolean): LiveBucket {
|
|
89
|
+
function finish(a: Acc, lateNight: boolean, streakMin = Math.round(a.maxStreakMs / 60000)): LiveBucket {
|
|
87
90
|
const m = a.m;
|
|
88
91
|
m.sessions = a.sessions.size;
|
|
89
92
|
m.activeMin = a.slots.size * 5;
|
|
90
|
-
m.streakMin =
|
|
93
|
+
m.streakMin = streakMin;
|
|
91
94
|
m.decisions = m.interrupts + m.rejects + m.questions + m.plans + m.modeSwitches;
|
|
92
95
|
m.lateNight = lateNight;
|
|
93
96
|
return { ...m, score: score(m) };
|
|
@@ -134,10 +137,10 @@ function foldEvents(sorted: Event[], startMs: number): { acc: Map<string, Acc>;
|
|
|
134
137
|
// runs from the first event, so a streak older than the window is measured from
|
|
135
138
|
// where it began. Events before the day's start count here, unlike in a bucket:
|
|
136
139
|
// the window is a clock's hour, not a calendar's.
|
|
137
|
-
function foldLive(sorted: Event[], nowMs: number): Acc {
|
|
140
|
+
function foldLive(sorted: Event[], nowMs: number, sinceMs = -Infinity): Acc {
|
|
138
141
|
const a = newAcc();
|
|
139
142
|
const fromMs = nowMs - LIVE_MS;
|
|
140
|
-
const inWindow = (t: number): boolean => t > fromMs && t <= nowMs;
|
|
143
|
+
const inWindow = (t: number): boolean => t > fromMs && t >= sinceMs && t <= nowMs;
|
|
141
144
|
let prevPresenceTs: number | null = null;
|
|
142
145
|
let streakStart = 0;
|
|
143
146
|
for (const e of sorted) {
|
|
@@ -152,6 +155,25 @@ function foldLive(sorted: Event[], nowMs: number): Acc {
|
|
|
152
155
|
return a;
|
|
153
156
|
}
|
|
154
157
|
|
|
158
|
+
// statusOf reads this streakMin; a break before the streak cools the score.
|
|
159
|
+
function liveBucket(sorted: Event[], presenceTs: number[], presence: Day["presence"], nowMs: number, lateNight: boolean): LiveBucket {
|
|
160
|
+
const lastMs = presence ? Date.parse(presence.lastAt) : null;
|
|
161
|
+
const startMs = lastMs !== null && nowMs - lastMs <= GAP_MS ? Date.parse(presence!.streakStartAt) : null;
|
|
162
|
+
const streakMin = startMs === null ? 0 : Math.min(MAX_STREAK_MIN, Math.round((nowMs - startMs) / 60000));
|
|
163
|
+
const full = finish(foldLive(sorted, nowMs), lateNight, streakMin);
|
|
164
|
+
if (full.score === null) return full;
|
|
165
|
+
const f = fractionsOf(full);
|
|
166
|
+
const after = startMs === null ? null : fractionsOf(finish(foldLive(sorted, nowMs, startMs), lateNight, streakMin));
|
|
167
|
+
const breakFrom = startMs === null ? lastMs : presenceTs.findLast((t) => t < startMs);
|
|
168
|
+
const w = breakFrom == null ? 0 : Math.max(0, 1 - ((startMs ?? nowMs) - breakFrom) / (NORMS.coolMin * 60_000));
|
|
169
|
+
const cooled = { ...f };
|
|
170
|
+
for (const p of Object.keys(f) as Part[]) {
|
|
171
|
+
const a = after?.[p] ?? 0;
|
|
172
|
+
cooled[p] = a + w * (f[p] - a);
|
|
173
|
+
}
|
|
174
|
+
return { ...full, score: scoreOf(cooled) };
|
|
175
|
+
}
|
|
176
|
+
|
|
155
177
|
function buildDay(date: string, acc: Map<string, Acc>): Day {
|
|
156
178
|
const buckets: HourBucket[] = [];
|
|
157
179
|
// Hours run in time order, so the last write is the day's last action.
|
|
@@ -214,7 +236,8 @@ export function derive(events: Event[], w: Window): Day[] {
|
|
|
214
236
|
const open = days.find((d) => d.date === today);
|
|
215
237
|
if (open) {
|
|
216
238
|
open.asOf = w.now.toISOString();
|
|
217
|
-
|
|
239
|
+
const presenceTs = read.filter((e) => PRESENCE.has(e.kind)).map((e) => e.ts);
|
|
240
|
+
open.live = liveBucket(sorted, presenceTs, open.presence, w.now.getTime(), LATE_HOURS.has(w.now.getHours()));
|
|
218
241
|
}
|
|
219
242
|
}
|
|
220
243
|
return days;
|
package/src/lib/metrics/index.ts
CHANGED
package/src/lib/metrics/score.ts
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
import type { Level, Metrics, Parts, Score } from "../types.ts";
|
|
1
|
+
import type { Level, Metrics, Part, Parts, Score } from "../types.ts";
|
|
2
2
|
|
|
3
3
|
// Calibration lives here and nowhere else. Integer points of 100, so 0.5 sums
|
|
4
4
|
// stay exact; norms are the p90 of two weeks on two machines (see CHANGELOG).
|
|
5
5
|
export const WEIGHTS = { parallel: 25, pace: 15, supervision: 30, reading: 10, streak: 10, late: 10 } as const;
|
|
6
|
-
export const NORMS = { parallelSpan: 4, pacePerHour: 20, supervisionPerHour: 45, decisionWeight: 3, readingTokens: 80_000, streakMin: 40 } as const;
|
|
6
|
+
export const NORMS = { parallelSpan: 4, pacePerHour: 20, supervisionPerHour: 45, decisionWeight: 3, readingTokens: 80_000, streakMin: 40, coolMin: 20 } as const;
|
|
7
7
|
const LEVELS: readonly { max: number; level: Level }[] = [
|
|
8
8
|
{ max: 29, level: "Calm" },
|
|
9
9
|
{ max: 59, level: "Warming" },
|
|
@@ -11,6 +11,8 @@ const LEVELS: readonly { max: number; level: Level }[] = [
|
|
|
11
11
|
{ max: 100, level: "Fried" },
|
|
12
12
|
];
|
|
13
13
|
|
|
14
|
+
const BY_WEIGHT = (Object.keys(WEIGHTS) as Part[]).sort((a, b) => WEIGHTS[b] - WEIGHTS[a]);
|
|
15
|
+
|
|
14
16
|
const clamp01 = (x: number): number => Math.min(1, Math.max(0, x));
|
|
15
17
|
|
|
16
18
|
export function levelOf(index: number): Level {
|
|
@@ -18,8 +20,13 @@ export function levelOf(index: number): Level {
|
|
|
18
20
|
return "Fried";
|
|
19
21
|
}
|
|
20
22
|
|
|
23
|
+
export type Fractions = Record<Part, number>;
|
|
24
|
+
|
|
21
25
|
export function score(m: Metrics): Score | null {
|
|
22
|
-
|
|
26
|
+
return m.sessions === 0 ? null : scoreOf(fractionsOf(m));
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export function fractionsOf(m: Metrics): Fractions {
|
|
23
30
|
const parallel = clamp01((m.sessions - 1) / NORMS.parallelSpan);
|
|
24
31
|
const pace = clamp01(m.prompts / NORMS.pacePerHour);
|
|
25
32
|
// A decision costs `decisionWeight` reports or session hops; the three share a norm.
|
|
@@ -29,6 +36,13 @@ export function score(m: Metrics): Score | null {
|
|
|
29
36
|
const reading = clamp01(m.outputTokens / NORMS.readingTokens);
|
|
30
37
|
const streak = clamp01(m.streakMin / NORMS.streakMin);
|
|
31
38
|
const late = m.lateNight ? 1 : 0;
|
|
39
|
+
return { parallel, pace, supervision, reading, streak, late };
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export function scoreOf(fractions: Fractions): Score {
|
|
43
|
+
const { parallel, pace, supervision, reading, streak, late } = fractions;
|
|
44
|
+
const capped = BY_WEIGHT.filter((p) => fractions[p] === 1);
|
|
45
|
+
const top = BY_WEIGHT.reduce((a, b) => (fractions[b] > fractions[a] ? b : a));
|
|
32
46
|
|
|
33
47
|
const raw = {
|
|
34
48
|
parallel: WEIGHTS.parallel * parallel,
|
|
@@ -51,5 +65,5 @@ export function score(m: Metrics): Score | null {
|
|
|
51
65
|
const index = Math.round(
|
|
52
66
|
raw.parallel + raw.pace + raw.supervision + raw.reading + raw.streak + raw.late,
|
|
53
67
|
);
|
|
54
|
-
return { index, level: levelOf(index), parts };
|
|
68
|
+
return { index, level: levelOf(index), parts, capped, top };
|
|
55
69
|
}
|
package/src/lib/status/status.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { GAP_MS } from "../metrics/index.ts";
|
|
1
|
+
import { GAP_MS, MAX_STREAK_MIN, NORMS } from "../metrics/index.ts";
|
|
2
2
|
import type { Day, Level } from "../types.ts";
|
|
3
3
|
|
|
4
|
-
// The status file's
|
|
4
|
+
// The status file's eleven values. The field order is the file format.
|
|
5
5
|
export type Status = {
|
|
6
6
|
schema: 1;
|
|
7
7
|
asOf: string;
|
|
@@ -12,17 +12,15 @@ export type Status = {
|
|
|
12
12
|
peak: number | null;
|
|
13
13
|
activeMin: number;
|
|
14
14
|
streakMin: number;
|
|
15
|
+
restAt: string | null;
|
|
16
|
+
restMin: number;
|
|
15
17
|
};
|
|
16
18
|
|
|
17
|
-
// The reader contract's ceiling for activeMin and streakMin (status file spec):
|
|
18
|
-
// a reader treats a larger value as no data, so a longer streak is written as this.
|
|
19
|
-
const MAX_MIN = 1500;
|
|
20
|
-
|
|
21
19
|
// How far back `status` reads to find where the live streak began: as far as
|
|
22
20
|
// the file can show it, and one gap more, so that a streak longer than that
|
|
23
|
-
// still reaches past the ceiling
|
|
21
|
+
// still reaches past the ceiling instead of reading a few minutes under it.
|
|
24
22
|
export function streakFrom(now: Date): Date {
|
|
25
|
-
return new Date(now.getTime() -
|
|
23
|
+
return new Date(now.getTime() - MAX_STREAK_MIN * 60_000 - GAP_MS);
|
|
26
24
|
}
|
|
27
25
|
|
|
28
26
|
// index and level are the day's `live` bucket, not the hour's: an hour's bucket
|
|
@@ -33,7 +31,7 @@ export function streakFrom(now: Date): Date {
|
|
|
33
31
|
export function statusOf(day: Day, now: Date): Status {
|
|
34
32
|
const hour = now.getHours();
|
|
35
33
|
const index = day.live?.score?.index ?? null;
|
|
36
|
-
const
|
|
34
|
+
const streakMin = day.live?.streakMin ?? 0;
|
|
37
35
|
return {
|
|
38
36
|
schema: 1,
|
|
39
37
|
asOf: day.asOf ?? now.toISOString(),
|
|
@@ -43,7 +41,9 @@ export function statusOf(day: Day, now: Date): Status {
|
|
|
43
41
|
level: day.live?.score?.level ?? null,
|
|
44
42
|
peak: index === null ? day.peak : Math.max(index, day.peak ?? 0),
|
|
45
43
|
activeMin: day.activeMin,
|
|
46
|
-
streakMin
|
|
44
|
+
streakMin,
|
|
45
|
+
restAt: streakMin > 0 ? new Date(Date.parse(day.presence!.streakStartAt) + NORMS.streakMin * 60000).toISOString() : null,
|
|
46
|
+
restMin: GAP_MS / 60000,
|
|
47
47
|
};
|
|
48
48
|
}
|
|
49
49
|
|
package/src/lib/types.ts
CHANGED
|
@@ -11,7 +11,8 @@ export type Metrics = {
|
|
|
11
11
|
};
|
|
12
12
|
export type Level = "Calm" | "Warming" | "Heating" | "Fried";
|
|
13
13
|
export type Parts = { parallel: number; pace: number; supervision: number; reading: number; streak: number; late: number }; // weighted points, sum ≈ index
|
|
14
|
-
export type
|
|
14
|
+
export type Part = keyof Parts;
|
|
15
|
+
export type Score = { index: number; level: Level; parts: Parts; capped: Part[]; top: Part };
|
|
15
16
|
export type LiveBucket = Metrics & { score: Score | null };
|
|
16
17
|
export type HourBucket = LiveBucket & { hour: number };
|
|
17
18
|
export type Totals = { prompts: number; reports: number; outputTokens: number; interrupts: number; rejects: number; questions: number; plans: number; modeSwitches: number; decisions: number; contextSwitches: number; maxSessions: number };
|