@drakulavich/cogload 0.16.0 → 0.17.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 CHANGED
@@ -5,6 +5,25 @@ All notable changes to this project are documented here. The format follows
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [0.17.0] - 2026-11-22
9
+
10
+ ### Added
11
+ - `cogload trend [window]` shows a window in one screen: the share of hours
12
+ by level, one line per week and the mean index by sessions in the hour.
13
+ It covers the last 28 days by default and prints text even in a pipe;
14
+ `--json` prints the counts. (#256)
15
+ - `--explain` now shows how far over its norm a part at its cap is:
16
+ `25 2.5×` for an hour with 11 sessions, where it printed `25` as for 5.
17
+ The index, the plain day table and the JSON are unchanged. (#254)
18
+
19
+ ## [0.16.1] - 2026-11-19
20
+
21
+ ### Fixed
22
+ - A skill or slash command sent during a rest now runs when the rest ends.
23
+ Claude Code refuses a plugin's prompt that begins with `/`, so before this
24
+ fix the queued command never went. A queued prompt that Claude Code or a
25
+ hook refuses now stays in the box, and a toast says so once. (#249)
26
+
8
27
  ## [0.16.0] - 2026-11-18
9
28
 
10
29
  ### Added
package/README.md CHANGED
@@ -50,6 +50,7 @@ Restart Claude Code to load the plugin. With a Homebrew Bun, put `~/.bun/bin` on
50
50
  cogload # the last 7 days
51
51
  cogload yesterday --explain # one day, with the components behind each index
52
52
  cogload card # the picture
53
+ cogload trend # the last four weeks in one screen
53
54
  ```
54
55
 
55
56
  ## What it looks like
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@drakulavich/cogload",
3
- "version": "0.16.0",
3
+ "version": "0.17.0",
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/args.ts CHANGED
@@ -3,6 +3,7 @@ import { localDate } from "../lib/metrics/index.ts";
3
3
  export const USAGE = `usage: cogload [window] the last 7 days, one cell per hour
4
4
  cogload today|yesterday|<date> one day, one row per active hour
5
5
  cogload card [window] [--out] the last 14 days as one picture
6
+ cogload trend [window] the last 28 days in one screen
6
7
  cogload status write today's load for a status line
7
8
 
8
9
  window:
@@ -28,7 +29,7 @@ bugs, ideas and a star: github.com/drakulavich/cogload`;
28
29
  export const HINT = "run 'cogload --help' for usage";
29
30
 
30
31
  export type Args = {
31
- command: "grid" | "day" | "card" | "status";
32
+ command: "grid" | "day" | "card" | "trend" | "status";
32
33
  to: string;
33
34
  days: number;
34
35
  explain: boolean;
@@ -191,7 +192,7 @@ export function parseArgs(argv: string[], now: Date, env: Record<string, string
191
192
  if (positional.length > 1) throw new UsageError(`unexpected argument${named(positional[1]!)}`);
192
193
  const [word] = positional;
193
194
  if (word === undefined) a.command = "grid";
194
- else if (word === "card") a.command = "card";
195
+ else if (word === "card" || word === "trend") a.command = word;
195
196
  else if (word === "status") {
196
197
  a.command = "status";
197
198
  a.to = localDate(now);
@@ -200,16 +201,16 @@ export function parseArgs(argv: string[], now: Date, env: Record<string, string
200
201
  a.command = "day";
201
202
  a.to = resolveDate("date", word, now);
202
203
  a.days = 1;
203
- } else throw new UsageError(`unknown command${named(word)} (try today, yesterday, a date, card or status)`);
204
+ } else throw new UsageError(`unknown command${named(word)} (try today, yesterday, a date, card, trend or status)`);
204
205
 
205
206
  if (a.command === "day" || a.command === "status") {
206
207
  if (days !== null || from !== null || to !== null)
207
208
  throw new UsageError(`--days, --from and --to do not apply to ${a.command === "day" ? "a named day" : "status"}`);
208
209
  } else {
209
- ({ to: a.to, days: a.days } = windowOf(days, from, to, a.command === "card" ? 14 : 7, now));
210
+ ({ to: a.to, days: a.days } = windowOf(days, from, to, a.command === "card" ? 14 : a.command === "trend" ? 28 : 7, now));
210
211
  }
211
- // The card is a file either way, so only an explicit --json switches it.
212
- a.json = a.command === "card" ? jsonFlag : jsonFlag || !isTTY;
212
+ // The card is a file and a trend something to paste, so only an explicit --json switches them.
213
+ a.json = a.command === "card" || a.command === "trend" ? jsonFlag : jsonFlag || !isTTY;
213
214
  if (a.command !== "day" && a.explain) throw new UsageError("--explain applies to a named day only");
214
215
  if (a.command !== "card" && a.out !== null) throw new UsageError("--out applies to card only");
215
216
  if (a.json && a.out !== null) throw new UsageError("--json writes no file; drop --out");
@@ -2,9 +2,10 @@ import { statSync } from "node:fs";
2
2
  import { homedir } from "node:os";
3
3
  import { basename, join } from "node:path";
4
4
  import { CardWriteError, cardData, cardHtml, loadAssets, openCard, renderCard, sentenceText } from "../lib/card/index.ts";
5
+ import { trendOf } from "../lib/metrics/index.ts";
5
6
  import { report, type Timing } from "../lib/report/index.ts";
6
7
  import { renderStatus, statusOf, streakFrom, writeStatus } from "../lib/status/index.ts";
7
- import { renderDay, renderJson, renderWeek } from "../lib/text/index.ts";
8
+ import { renderDay, renderJson, renderTrend, renderWeek } from "../lib/text/index.ts";
8
9
  import type { TranscriptCache } from "../lib/transcripts/index.ts";
9
10
  import type { Day } from "../lib/types.ts";
10
11
  import type { Args } from "./args.ts";
@@ -18,6 +19,12 @@ export async function table(a: Args, now: Date, cache: TranscriptCache | null, t
18
19
  return 0;
19
20
  }
20
21
 
22
+ export async function trend(a: Args, now: Date, cache: TranscriptCache | null, timing?: Timing): Promise<number> {
23
+ const t = trendOf(await report({ projects: a.projects, to: a.to, days: a.days, now }, timing, cache));
24
+ process.stdout.write(`${a.json ? JSON.stringify(t, null, 2) : renderTrend(t, a.color)}\n`);
25
+ return 0;
26
+ }
27
+
21
28
  // The write comes first: a caller never reads a line that was not saved.
22
29
  export async function status(a: Args, now: Date, cache: TranscriptCache | null, timing?: Timing): Promise<number> {
23
30
  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now, streakFrom: streakFrom(now) }, timing, cache);
package/src/cli/index.ts CHANGED
@@ -5,7 +5,7 @@ import { join } from "node:path";
5
5
  import { openCache } from "../lib/transcripts/index.ts";
6
6
  import type { Timing } from "../lib/report/index.ts";
7
7
  import { HelpRequested, HINT, parseArgs, USAGE, UsageError, VersionRequested } from "./args.ts";
8
- import { card, status, table } from "./commands.io.ts";
8
+ import { card, status, table, trend } from "./commands.io.ts";
9
9
  import { timingLines } from "./timing.ts";
10
10
 
11
11
  // Read only when --version is handled, so a broken package.json fails inside
@@ -45,9 +45,11 @@ async function main(): Promise<number> {
45
45
  const code =
46
46
  a.command === "card"
47
47
  ? await card(a, now, cache, timing)
48
- : a.command === "status"
49
- ? await status(a, now, cache, timing)
50
- : await table(a, now, cache, timing);
48
+ : a.command === "trend"
49
+ ? await trend(a, now, cache, timing)
50
+ : a.command === "status"
51
+ ? await status(a, now, cache, timing)
52
+ : await table(a, now, cache, timing);
51
53
  if (timing) process.stderr.write(timingLines(timing, runEnv()));
52
54
  return code;
53
55
  } finally {
@@ -1,3 +1,4 @@
1
1
  export { analyze, analyzeEvents } from "./analyze.ts";
2
2
  export { GAP_MS, localDate, MAX_STREAK_MIN, windowBounds } from "./derive.ts";
3
- export { levelOf, NORMS, score, WEIGHTS } from "./score.ts";
3
+ export { levelOf, NORMS, overOf, score, WEIGHTS } from "./score.ts";
4
+ export { type Trend, trendOf } from "./trend.ts";
@@ -34,15 +34,29 @@ export function score(m: Metrics): Score | null {
34
34
  return m.sessions === 0 ? null : scoreOf(fractionsOf(m));
35
35
  }
36
36
 
37
+ function rawOf(m: Metrics): Record<Exclude<Part, "late">, number> {
38
+ return {
39
+ parallel: (m.sessions - 1) / NORMS.parallelSpan,
40
+ pace: m.prompts / NORMS.pacePerHour,
41
+ // A decision costs `decisionWeight` reports or session hops; the three share a norm.
42
+ supervision: (NORMS.decisionWeight * m.decisions + m.reports + m.contextSwitches) / NORMS.supervisionPerHour,
43
+ reading: m.outputTokens / NORMS.readingTokens,
44
+ streak: m.streakMin / NORMS.streakMin,
45
+ };
46
+ }
47
+
48
+ export const overOf = (m: Metrics): Partial<Record<Exclude<Part, "late">, number>> => Object.fromEntries(Object.entries(rawOf(m)).filter(([, x]) => x >= 1));
49
+
37
50
  export function fractionsOf(m: Metrics): Fractions {
38
- const parallel = clamp01((m.sessions - 1) / NORMS.parallelSpan);
39
- const pace = clamp01(m.prompts / NORMS.pacePerHour);
40
- // A decision costs `decisionWeight` reports or session hops; the three share a norm.
41
- const supervision = clamp01((NORMS.decisionWeight * m.decisions + m.reports + m.contextSwitches) / NORMS.supervisionPerHour);
42
- const reading = clamp01(m.outputTokens / NORMS.readingTokens);
43
- const streak = clamp01(m.streakMin / NORMS.streakMin);
44
- const late = m.lateNight ? 1 : 0;
45
- return { parallel, pace, supervision, reading, streak, late };
51
+ const r = rawOf(m);
52
+ return {
53
+ parallel: clamp01(r.parallel),
54
+ pace: clamp01(r.pace),
55
+ supervision: clamp01(r.supervision),
56
+ reading: clamp01(r.reading),
57
+ streak: clamp01(r.streak),
58
+ late: m.lateNight ? 1 : 0,
59
+ };
46
60
  }
47
61
 
48
62
  export function scoreOf(fractions: Fractions): Score {
@@ -0,0 +1,59 @@
1
+ import type { Day, HourBucket, Level } from "../types.ts";
2
+
3
+ type TrendWeek = { from: string; to: string; days: number; hours: number; activeMin: number; hot: number; prompts: number };
4
+ export type Trend = {
5
+ from: string;
6
+ to: string;
7
+ days: number;
8
+ hours: number;
9
+ activeMin: number;
10
+ levels: Record<Level, number>;
11
+ weeks: TrendWeek[];
12
+ bySessions: { sessions: number; hours: number; mean: number | null }[];
13
+ asOf?: string;
14
+ };
15
+
16
+ const scored = (days: Day[]): HourBucket[] => days.flatMap((d) => d.buckets.filter((b) => b.score !== null));
17
+ const sumActive = (days: Day[]): number => days.reduce((s, d) => s + d.activeMin, 0);
18
+
19
+ // Weeks are the grid's: seven days ending on the window's last day, the first block shorter.
20
+ function weeksOf(days: Day[]): TrendWeek[] {
21
+ const weeks: TrendWeek[] = [];
22
+ for (let end = days.length; end > 0; end -= 7) {
23
+ const block = days.slice(Math.max(0, end - 7), end);
24
+ const hours = scored(block);
25
+ weeks.unshift({
26
+ from: block[0]!.date,
27
+ to: block[block.length - 1]!.date,
28
+ days: block.length,
29
+ hours: hours.length,
30
+ activeMin: sumActive(block),
31
+ hot: hours.filter((b) => b.score!.index >= 60).length,
32
+ prompts: block.reduce((s, d) => s + d.totals.prompts, 0),
33
+ });
34
+ }
35
+ return weeks;
36
+ }
37
+
38
+ export function trendOf(days: Day[]): Trend {
39
+ const hours = scored(days);
40
+ const levels: Record<Level, number> = { Calm: 0, Warming: 0, Heating: 0, Fried: 0 };
41
+ for (const b of hours) levels[b.score!.level]++;
42
+ const bySessions = [1, 2, 3, 4, 5].map((sessions) => {
43
+ const group = hours.filter((b) => Math.min(b.sessions, 5) === sessions);
44
+ const mean = group.length === 0 ? null : Math.round(group.reduce((s, b) => s + b.score!.index, 0) / group.length);
45
+ return { sessions, hours: group.length, mean };
46
+ });
47
+ const asOf = days.find((d) => d.asOf)?.asOf;
48
+ return {
49
+ from: days[0]!.date,
50
+ to: days[days.length - 1]!.date,
51
+ days: days.length,
52
+ hours: hours.length,
53
+ activeMin: sumActive(days),
54
+ levels,
55
+ weeks: weeksOf(days),
56
+ bySessions,
57
+ ...(asOf ? { asOf } : {}),
58
+ };
59
+ }
@@ -1,2 +1,2 @@
1
1
  export { formatCount, formatTokens, plural } from "./format.ts";
2
- export { renderDay, renderJson, renderWeek } from "./render.ts";
2
+ export { renderDay, renderJson, renderTrend, renderWeek } from "./render.ts";
@@ -1,6 +1,6 @@
1
1
  import { formatCount, plural } from "./format.ts";
2
- import { levelOf } from "../metrics/index.ts";
3
- import type { Day, HourBucket, Level } from "../types.ts";
2
+ import { levelOf, overOf, type Trend } from "../metrics/index.ts";
3
+ import type { Day, HourBucket, Level, Part } from "../types.ts";
4
4
 
5
5
  const GLYPH: Record<Level, string> = { Calm: "░", Warming: "▒", Heating: "▓", Fried: "█" };
6
6
  const ANSI: Record<Level, string> = { Calm: "32", Warming: "33", Heating: "38;5;208", Fried: "31" };
@@ -14,8 +14,8 @@ const hm = (min: number) => `${Math.floor(min / 60)}h${String(min % 60).padStart
14
14
  const hhmm = (d: Date) => `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
15
15
  // Marks the snapshot time on the open day, so two runs minutes apart are
16
16
  // explained rather than silently disagreeing.
17
- const snapshotLine = (d: Day | undefined, color: boolean): string[] =>
18
- d?.asOf ? [dim(` as of ${hhmm(new Date(d.asOf))}, this hour is still running`, color)] : [];
17
+ const snapshotLine = (asOf: string | undefined, color: boolean): string[] =>
18
+ asOf ? [dim(` as of ${hhmm(new Date(asOf))}, this hour is still running`, color)] : [];
19
19
  // The weekday of the calendar date, in UTC: a date the local zone skipped
20
20
  // has no local midnight to ask.
21
21
  const label = (date: string) => {
@@ -49,17 +49,7 @@ export function renderWeek(days: Day[], color: boolean): string {
49
49
  color,
50
50
  );
51
51
  // Today need not be the last row: --to may name a later day.
52
- return [
53
- header,
54
- ...rows,
55
- "",
56
- legend,
57
- totals,
58
- ...snapshotLine(
59
- days.find((d) => d.asOf),
60
- color,
61
- ),
62
- ].join("\n");
52
+ return [header, ...rows, "", legend, totals, ...snapshotLine(days.find((d) => d.asOf)?.asOf, color)].join("\n");
63
53
  }
64
54
 
65
55
  const fmtTokens = (n: number): string => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
@@ -83,14 +73,22 @@ const COLS: Col[] = [
83
73
  ["streak", 8, (b) => `${b.streakMin}m`],
84
74
  ["out-tok", 9, (b) => fmtTokens(b.outputTokens)],
85
75
  ];
76
+ const partCell =
77
+ (part: Exclude<Part, "late">) =>
78
+ (b: HourBucket): string => {
79
+ const points = String(b.score?.parts[part] ?? "");
80
+ const over = overOf(b)[part];
81
+ return over === undefined ? points : `${points} ${(Math.round(over * 10) / 10).toFixed(1)}×`;
82
+ };
86
83
  const EXPLAIN: Col[] = [
87
- ["par", 5, (b) => String(b.score?.parts.parallel ?? "")],
88
- ["pace", 6, (b) => String(b.score?.parts.pace ?? "")],
89
- ["sup", 6, (b) => String(b.score?.parts.supervision ?? "")],
90
- ["read", 6, (b) => String(b.score?.parts.reading ?? "")],
91
- ["strk", 6, (b) => String(b.score?.parts.streak ?? "")],
84
+ ["par", 10, partCell("parallel")],
85
+ ["pace", 10, partCell("pace")],
86
+ ["sup", 10, partCell("supervision")],
87
+ ["read", 10, partCell("reading")],
88
+ ["strk", 10, partCell("streak")],
92
89
  ["late", 6, (b) => String(b.score?.parts.late ?? "")],
93
90
  ];
91
+ const OVER_LEGEND = " N× beside a part: it is at its cap, with N times what fills it";
94
92
  // Left out of the table for a day where every active bucket reads zero; the
95
93
  // other columns always show, so two days still line up.
96
94
  const EVENT_COLS = new Set(["rep", "intr", "rej", "quest", "plan", "mode", "ctx-sw"]);
@@ -120,7 +118,7 @@ export function renderDay(day: Day, opts: { explain: boolean; color: boolean }):
120
118
  const active = day.buckets.filter((b) => b.score !== null);
121
119
  // The snapshot line still shows on an empty open day, or a run at 09:00 and
122
120
  // one at 18:00 would print the identical line.
123
- if (active.length === 0) return [`no activity on ${day.date}`, ...snapshotLine(day, opts.color)].join("\n");
121
+ if (active.length === 0) return [`no activity on ${day.date}`, ...snapshotLine(day.asOf, opts.color)].join("\n");
124
122
 
125
123
  const visible = cols.filter(([name, , f]) => !EVENT_COLS.has(name) || active.some((b) => f(b) !== "0"));
126
124
  const leftOut = cols.filter((col) => EVENT_COLS.has(col[0]) && !visible.includes(col));
@@ -140,10 +138,42 @@ export function renderDay(day: Day, opts: { explain: boolean; color: boolean }):
140
138
  const note = ` no ${leftOut.map(([name]) => FULL_NAME[name]).join(", ")} today`;
141
139
  lines.push(dim(note, opts.color));
142
140
  }
143
- lines.push(...snapshotLine(day, opts.color));
141
+ if (opts.explain && active.some((b) => Object.keys(overOf(b)).length > 0)) lines.push(dim(OVER_LEGEND, opts.color));
142
+ lines.push(...snapshotLine(day.asOf, opts.color));
144
143
  return lines.join("\n");
145
144
  }
146
145
 
147
146
  export function renderJson(data: Day[] | Day): string {
148
147
  return JSON.stringify(data, null, 2);
149
148
  }
149
+
150
+ export function renderTrend(t: Trend, color: boolean): string {
151
+ const head = `${label(t.from)} to ${label(t.to)}, ${plural(t.days, "day")}: ${plural(t.hours, "hour")} with a session, ${hm(t.activeMin)} active`;
152
+ if (t.hours === 0)
153
+ return [head, t.from === t.to ? `no activity on ${t.to}` : `no activity from ${t.from} to ${t.to}`, ...snapshotLine(t.asOf, color)].join("\n");
154
+ const levels = LEVELS.map((l) => {
155
+ const name = LEVEL_NAME[l];
156
+ const share = `${Math.round((100 * t.levels[l]) / t.hours)}%`;
157
+ return `${paint(name, l, color)}${" ".repeat(11 - name.length)}${String(t.levels[l]).padStart(5)}${share.padStart(7)}`;
158
+ });
159
+ const weeks = t.weeks.map(
160
+ (w) =>
161
+ `${label(w.from).padEnd(12)}${String(w.days).padStart(4)}${String(w.hours).padStart(7)}${hm(w.activeMin).padStart(8)}${String(w.hot).padStart(10)}${String(w.prompts).padStart(9)}`,
162
+ );
163
+ const sessions = t.bySessions.map(
164
+ (s) => `${(s.sessions === 5 ? "5+" : String(s.sessions)).padEnd(10)}${String(s.hours).padStart(5)}${(s.mean === null ? "-" : String(s.mean)).padStart(12)}`,
165
+ );
166
+ return [
167
+ head,
168
+ "",
169
+ "level hours share",
170
+ ...levels,
171
+ "",
172
+ "week from days hours active heating+ prompts",
173
+ ...weeks,
174
+ "",
175
+ "sessions hours mean index",
176
+ ...sessions,
177
+ ...snapshotLine(t.asOf, color),
178
+ ].join("\n");
179
+ }