kaizen-agent 1.62.0 → 1.64.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.
Files changed (51) hide show
  1. package/cli/automations.test.ts +167 -0
  2. package/cli/automations.ts +298 -0
  3. package/cli/dashboard.ts +1 -7
  4. package/cli/handoff.test.ts +133 -0
  5. package/cli/handoff.ts +122 -0
  6. package/cli/install.test.ts +16 -0
  7. package/cli/install.ts +92 -191
  8. package/cli/look.ts +33 -0
  9. package/cli/pty.ts +16 -2
  10. package/cli/resources.test.ts +50 -0
  11. package/cli/resources.ts +113 -0
  12. package/cli/restart.test.ts +28 -1
  13. package/cli/settings.ts +6 -2
  14. package/cli/setup.test.ts +22 -2
  15. package/cli/setup.ts +101 -51
  16. package/cli/sources.ts +1 -1
  17. package/cli/state.test.ts +7 -0
  18. package/cli/state.ts +13 -2
  19. package/cli/usage.test.ts +11 -0
  20. package/cli/web.ts +134 -6
  21. package/cli/workers.ts +11 -4
  22. package/cli/worktree.test.ts +174 -1
  23. package/cli/worktree.ts +190 -35
  24. package/package.json +1 -1
  25. package/skills/kaizen/config.default.yml +17 -0
  26. package/skills/kaizen/settings.md +4 -0
  27. package/skills/kaizen/spec-build.md +13 -0
  28. package/skills/kaizen/spec-main.md +13 -0
  29. package/skills/kaizen-help/SKILL.md +1 -0
  30. package/skills/media/kaizen-deck/SKILL.md +21 -2
  31. package/skills/media/kaizen-deck/scripts/motion.py +99 -0
  32. package/web/board/cards.ts +1 -0
  33. package/web/board/git.ts +4 -4
  34. package/web/board/phone.ts +5 -5
  35. package/web/board/resources.ts +152 -0
  36. package/web/board/run-view.ts +107 -1
  37. package/web/board/search.ts +6 -0
  38. package/web/board/settings-automations.ts +71 -0
  39. package/web/board/settings-pages.test.ts +4 -0
  40. package/web/board/settings-pages.ts +2 -1
  41. package/web/board/settings.ts +10 -3
  42. package/web/board/workspace.ts +7 -1
  43. package/web/board/ws-tabs.test.ts +20 -1
  44. package/web/board/ws-tabs.ts +26 -7
  45. package/web/board.html +20 -3
  46. package/web/board.js +119 -88
  47. package/web/notebook.js +23 -23
  48. package/web/notes.html +1 -0
  49. package/web/term.js +1 -1
  50. package/web/video.html +1 -0
  51. package/web/video.js +49 -49
package/cli/handoff.ts ADDED
@@ -0,0 +1,122 @@
1
+ // A worktree run handed to a second agent: the first agent stays with the user, the board opens
2
+ // the second in the worktree, and wakes the first when it ends. Its own file, not state.json,
3
+ // because agents hand-write state.json. The wake-up carries nothing: this file and the run's
4
+ // reports are the message, so a lost one costs only the nudge.
5
+ import { closeSync, existsSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
6
+ import { join } from "node:path";
7
+
8
+ export type Status = "requested" | "running" | "done" | "blocked" | "failed" | "declined" | "quiet";
9
+ export type Handoff = { status: Status; parent_terminal: string; child_terminal?: string; reason?: string; at: number; woken?: boolean };
10
+ export const REQUEST_MS = 10_000;
11
+ const QUIET_TYPING_MS = 5_000;
12
+ const DRAFT_MS = 10 * 60_000; // a draft untouched this long no longer holds the wake
13
+
14
+ const file = (state: string, id: string) => join(state, "runs", id, "handoff.json");
15
+
16
+ export function readHandoff(state: string, id: string): Handoff | null {
17
+ try { return JSON.parse(readFileSync(file(state, id), "utf8")); } catch { return null; }
18
+ }
19
+
20
+ export function writeHandoff(state: string, id: string, h: Handoff) {
21
+ const f = file(state, id), tmp = `${f}.${process.pid}.tmp`;
22
+ writeFileSync(tmp, JSON.stringify(h, null, 2));
23
+ renameSync(tmp, f);
24
+ }
25
+
26
+ // The CLI and the board both move this file, so every move holds a lock across its read and
27
+ // write and names the statuses it may leave: a stale reader changes nothing.
28
+ function locked<T>(state: string, id: string, fn: () => T): T {
29
+ const lock = `${file(state, id)}.lock`;
30
+ for (let i = 0; ; i++) {
31
+ try { closeSync(openSync(lock, "wx")); break; } catch (err) {
32
+ try { if (Date.now() - statSync(lock).mtimeMs > 5000) { rmSync(lock, { force: true }); continue; } } catch { /* just released */ }
33
+ if (i > 500) throw err;
34
+ Bun.sleepSync(2);
35
+ }
36
+ }
37
+ try { return fn(); } finally { rmSync(lock, { force: true }); }
38
+ }
39
+
40
+ /** Moves the handoff only if it is in one of `from`. True when it moved. */
41
+ export function move(state: string, id: string, from: Status[], set: Partial<Handoff>): boolean {
42
+ return locked(state, id, () => {
43
+ const h = readHandoff(state, id);
44
+ if (!h || !from.includes(h.status)) return false;
45
+ writeHandoff(state, id, { ...h, ...set, at: Date.now() });
46
+ return true;
47
+ });
48
+ }
49
+
50
+ /**
51
+ * Asks the board for the second agent. Null when this is no board terminal: build here. An
52
+ * agent already open, or a request still live, is returned as it is: never a second one.
53
+ */
54
+ export function request(state: string, id: string, term: string | undefined): Handoff | null {
55
+ if (!term || !existsSync(join(state, "runs", id, "state.json"))) return null;
56
+ return locked(state, id, () => {
57
+ const was = readHandoff(state, id);
58
+ if (was && (was.status === "running" || was.status === "quiet" || requestOpen(was, Date.now()))) return was;
59
+ const h: Handoff = { status: "requested", parent_terminal: term, at: Date.now() };
60
+ writeHandoff(state, id, h);
61
+ return h;
62
+ });
63
+ }
64
+
65
+ /**
66
+ * Waits for the board to answer. No answer declines the request, so a board that comes up
67
+ * later cannot open a second agent beside the one now building here. The decline can lose to
68
+ * the board's claim: then the agent is open, and this says so.
69
+ */
70
+ export async function awaitBoard(state: string, id: string, ms = REQUEST_MS, step = 200): Promise<boolean> {
71
+ const took = (s?: Status) => s === "running" || s === "quiet" || s === "done" || s === "blocked" || s === "failed";
72
+ const end = Date.now() + ms;
73
+ while (Date.now() < end) {
74
+ const s = readHandoff(state, id)?.status;
75
+ // A quick second agent may be finished by the time this looks: it still took the run.
76
+ if (took(s)) return true;
77
+ if (s !== "requested") return false;
78
+ await Bun.sleep(step);
79
+ }
80
+ if (move(state, id, ["requested"], { status: "declined", reason: "no board answered" })) return false;
81
+ return took(readHandoff(state, id)?.status);
82
+ }
83
+
84
+ /** The board's claim, made before anything launches: it loses to a decline, so no stray agent. */
85
+ export const started = (state: string, id: string, key: string) => move(state, id, ["requested"], { status: "running", child_terminal: key });
86
+ export const refused = (state: string, id: string, why: string) => move(state, id, ["requested"], { status: "declined", reason: why });
87
+
88
+ /** The second agent's last word. A repeat cannot rewrite the result; a report after `quiet` wakes the first agent again, since it is news. */
89
+ export function finish(state: string, id: string, status: "done" | "blocked", reason?: string): string | null {
90
+ const h = readHandoff(state, id);
91
+ if (!h) return "this run has no handoff";
92
+ return move(state, id, ["running", "quiet"], { status, reason, woken: false }) ? null : `the handoff is ${readHandoff(state, id)!.status}, not running`;
93
+ }
94
+
95
+ /** A request the board may still act on. An old one was declined or abandoned by its asker. */
96
+ export const requestOpen = (h: Handoff | null, now: number) => h?.status === "requested" && now - h.at < REQUEST_MS;
97
+
98
+ /** A live second agent silent this long, not working or asking: it may have ended without saying so. */
99
+ export const QUIET_MS = 20 * 60_000;
100
+ export const childQuiet = (h: Handoff | null, pty: { alive: boolean; busy: boolean; asking: boolean; lastOut?: number } | null, now: number) =>
101
+ h?.status === "running" && !!pty?.alive && !pty.busy && !pty.asking && now - (pty.lastOut ?? now) > QUIET_MS;
102
+
103
+ /** The child terminal ended without a report. */
104
+ export const childDied = (h: Handoff | null, alive: boolean) => (h?.status === "running" || h?.status === "quiet") && !alive;
105
+
106
+ type Term = { alive: boolean; busy: boolean; asking: boolean; typedAt: number; draft?: boolean } | null;
107
+ export type Wake = "wait" | "send" | "gone" | "held" | "none";
108
+
109
+ /** What to do about the first agent: send only into a live, idle terminal nobody is typing in. */
110
+ export function wakeAction(h: Handoff | null, parent: Term, now: number): Wake {
111
+ if (!h || h.woken || !["done", "blocked", "failed", "quiet"].includes(h.status)) return "none";
112
+ if (!parent?.alive) return "gone";
113
+ // Unsent text in its input box: a wake would submit that draft. The card speaks instead.
114
+ if (parent.draft && now - parent.typedAt < DRAFT_MS) return "held";
115
+ return parent.busy || parent.asking || now - parent.typedAt < QUIET_TYPING_MS ? "wait" : "send";
116
+ }
117
+
118
+ export const wakeLine = (id: string, h: Handoff) =>
119
+ `kaizen run ${id}: the worktree agent ended (${h.status}). Read .kaizen/runs/${id}/handoff.json, 03-impl.md and 04-review.md, then report to the user.`;
120
+
121
+ /** Marked before sending: a board restart between the two loses a nudge, never repeats one. */
122
+ export const markWoken = (state: string, id: string) => move(state, id, ["done", "blocked", "failed", "quiet"], { woken: true });
@@ -219,3 +219,19 @@ it("no agent, no terminal: the list is printed and nothing is installed", () =>
219
219
  expect(p.stdout.toString()).toContain("Install one, then run this again.");
220
220
  expect(ran).toBe(false);
221
221
  });
222
+
223
+ it("uninstall finishes when it runs from the ~/kaizen it deletes, as the launcher does", () => {
224
+ const root = mkdtempSync(join(tmpdir(), "kz-uninstall-"));
225
+ const home = join(root, "home"), k = join(home, "kaizen");
226
+ mkdirSync(home);
227
+ for (const d of ["cli", "skills", "web"]) cpSync(join(dirname(script), "..", d), join(k, d), { recursive: true });
228
+ cpSync(join(dirname(script), "..", "package.json"), join(k, "package.json"));
229
+ const p = Bun.spawnSync([process.execPath, join(k, "cli", "install.ts"), "uninstall", "--yes"], {
230
+ cwd: home, env: { PATH: process.env.PATH ?? "", HOME: home, USERPROFILE: home, TMPDIR: root },
231
+ });
232
+ const left = existsSync(k), out = p.stdout.toString(), code = p.exitCode;
233
+ rmSync(root, { recursive: true, force: true });
234
+ expect(code).toBe(0);
235
+ expect(left).toBe(false);
236
+ expect(out).toContain("Uninstalled");
237
+ });
package/cli/install.ts CHANGED
@@ -9,6 +9,7 @@ import { join, dirname, basename, resolve } from "node:path";
9
9
  import { homedir, tmpdir } from "node:os";
10
10
  import { ignoreKaizen } from "./add-project.ts";
11
11
  import { applyPreset, detectPreset, PRESETS, type PresetName } from "./settings.ts";
12
+ import { banner, c, nextSteps } from "./look.ts";
12
13
 
13
14
  // The real path: process.cwd() is always physical, so a raw $HOME that crosses a
14
15
  // symlink (/home -> var/home) would never compare equal to it, and the home
@@ -41,13 +42,6 @@ function parsePresetArg(): PresetName | null {
41
42
  }
42
43
  const presetArg = parsePresetArg();
43
44
 
44
- const c = {
45
- dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
46
- bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
47
- cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
48
- green: (s: string) => `\x1b[32m${s}\x1b[0m`,
49
- };
50
-
51
45
  // Skill folders shipped in skills/ and linked into every agent, by their last
52
46
  // path segment: media/kaizen-deck is linked as skills/kaizen-deck.
53
47
  const SKILLS = bundledSkills(dirname(import.meta.dir)).map((s) => s.rel);
@@ -124,6 +118,39 @@ if (Bun.argv[2] === "card") {
124
118
 
125
119
  // `kaizen computer <verb> ...`: desktop control through the accessibility tree, only while
126
120
  // the kaizen-computer skill is on. One JSON line out. See cli/computer.ts.
121
+ // `kaizen automation list | add | run | pause | resume | rm | runs`: schedules that start a run in this
122
+ // project. Fires happen while a board runs; `run` starts one now, in a terminal, without the precheck.
123
+ if (Bun.argv[2] === "automation") {
124
+ const A = await import("./automations.ts");
125
+ const { locate } = await import("./state.ts");
126
+ const state = locate() ?? join(home, ".kaizen");
127
+ const [verb, ...rest] = Bun.argv.slice(3);
128
+ const flag = (n: string) => { const i = rest.indexOf("--" + n); return i >= 0 ? rest.splice(i, 2)[1] : undefined; };
129
+ const fail = (m: string): never => { console.log(`\n ${m}\n`); process.exit(1); };
130
+ const rules = () => { try { return A.readRules(state); } catch (e: any) { return fail(e.message); } };
131
+ const find = (id?: string) => rules().find((r) => r.id === id) ?? fail("No such automation. See: kaizen automation list");
132
+ if (verb === "add") {
133
+ const input = { text: flag("text"), kind: flag("every"), time: flag("time"), day: flag("day"), cron: flag("cron"), precheck: flag("precheck"), grace_minutes: flag("grace"), agent: flag("agent"), name: rest.join(" ") };
134
+ if (input.cron && !input.kind) input.kind = "cron";
135
+ const r = A.addRule(state, input);
136
+ if (typeof r === "string") fail(`${r}\n kaizen automation add "<name>" --text "<request>" --every hourly|daily|weekdays|weekly [--time HH:MM] [--day mon] | --cron "<5 fields>" [--precheck "<cmd>"] [--grace N] [--agent <tool>]`);
137
+ else console.log(`\n ${c.green("added")} ${r.name} ${c.dim(`${r.id} · ${r.cron}`)}\n ${c.dim("Runs unattended in auto mode: it changes code and spends tokens with nobody watching.")}\n${r.precheck ? ` ${c.dim("precheck, runs on this computer every time it fires:")} ${r.precheck}\n` : ""}`);
138
+ } else if (verb === "list" || !verb) {
139
+ for (const r of rules()) { const n = A.nextRun(r.cron, Date.now()); console.log(` ${r.id} ${r.enabled ? "on " : "off"} ${r.cron.padEnd(14)} next ${n ? new Date(n).toLocaleString() : "never"} ${r.name}`); }
140
+ } else if (verb === "pause" || verb === "resume") {
141
+ const r = A.setEnabled(state, find(rest[0]).id, verb === "resume"); if (typeof r === "string") fail(r); console.log(`\n ${verb}d ${rest[0]}\n`);
142
+ } else if (verb === "rm") {
143
+ const r = A.removeRule(state, find(rest[0]).id); if (r) fail(r); console.log(`\n removed ${rest[0]}\n`);
144
+ } else if (verb === "run") {
145
+ const h = await A.fire(state, find(rest[0]), "manual", Date.now());
146
+ console.log(`\n ${h?.status}${h?.reason ? `: ${h.reason}` : ""}\n`); process.exit(h?.status === "launched" ? 0 : 1);
147
+ } else if (verb === "runs") {
148
+ const id = find(rest[0]).id;
149
+ for (const h of A.readHistory(state).filter((x) => x.rule === id).sort((a, b) => b.at - a.at)) { const v = A.shown(state, h); console.log(` ${new Date(h.at).toLocaleString()} ${h.kind.padEnd(9)} ${v.status}${v.run ? " " + v.run : ""}${h.reason ? " " + h.reason : ""}`); }
150
+ } else fail("kaizen automation list | add | run <id> | pause <id> | resume <id> | rm <id> | runs <id>");
151
+ process.exit(0);
152
+ }
153
+
127
154
  if (Bun.argv[2] === "computer") {
128
155
  const { computer } = await import("./computer.ts");
129
156
  const { out, code } = await computer(Bun.argv.slice(3), { home: homedir() });
@@ -288,7 +315,7 @@ if (Bun.argv[2] === "issue") {
288
315
  if (args.has("--env")) { console.log(systemInfo()); process.exit(0); }
289
316
  const what = Bun.argv.slice(3).join(" ");
290
317
  const url = issueUrl({ title: what.split("\n")[0], what });
291
- console.log(`\n ${c.cyan(url)}\n`);
318
+ console.log(`\n ${c.accent(url)}\n`);
292
319
  console.log(await openUrl(url)
293
320
  ? ` ${c.dim("Opened in your browser. Check it, then submit it on GitHub.")}\n`
294
321
  : ` ${c.dim("Open that link to file the issue.")}\n`);
@@ -336,6 +363,8 @@ async function removeEverything() {
336
363
  // projects live on other drives entirely. Every project kaizen knows about is
337
364
  // checked, plus whatever a drive-wide scan turns up.
338
365
  const { knownProjects, searchRoots, findProjects } = await import("./state.ts");
366
+ // Loaded now: the launcher runs this file from ~/kaizen, which is deleted below.
367
+ const { removeSessionHook } = await import("./knowledge.ts");
339
368
  step("looking for project installs");
340
369
  const roots = [home, process.cwd(), ...knownProjects(),
341
370
  ...searchRoots([process.cwd()]).flatMap((r) => findProjects(r))]
@@ -380,7 +409,6 @@ async function removeEverything() {
380
409
  drop(join(process.env.BUN_INSTALL ?? join(home, ".bun"), "bin", "kaizen.cmd"));
381
410
  drop(join(home, ".local", "bin", "kaizen"));
382
411
  {
383
- const { removeSessionHook } = await import("./knowledge.ts");
384
412
  if (removeSessionHook(join(home, ".claude", "settings.json"))) gone.push("the kaizen recall hook in ~/.claude/settings.json");
385
413
  }
386
414
  await clearBunxCache();
@@ -400,7 +428,7 @@ async function removeEverything() {
400
428
  }
401
429
  console.log(purge
402
430
  ? `\n ${c.dim("Runs and settings deleted too.")}\n`
403
- : `\n ${c.dim("Runs and settings kept in")} ${c.cyan(tilde(join(home, ".kaizen")))}${c.dim(" — add --purge to delete them.")}\n`);
431
+ : `\n ${c.dim("Runs and settings kept in")} ${c.accent(tilde(join(home, ".kaizen")))}${c.dim(" — add --purge to delete them.")}\n`);
404
432
  console.log(` ${c.dim("The CLAUDE.md / AGENTS.md line in each project is left for you to remove.")}\n`);
405
433
  }
406
434
 
@@ -450,11 +478,11 @@ async function noAgent(): Promise<boolean> {
450
478
  const docs = async (why = "") => {
451
479
  if (why) console.log(` ${why}`);
452
480
  console.log(` ${c.bold(pick.name)}`);
453
- console.log(` ${c.cyan(pick.docs)}\n`);
481
+ console.log(` ${c.accent(pick.docs)}\n`);
454
482
  const opened = await openUrl(pick.docs);
455
483
  console.log(opened
456
- ? ` ${c.dim("Opened in your browser. Install it, then run")} ${c.cyan("kaizen")} ${c.dim("again.")}`
457
- : ` ${c.dim("Open that page to install it, then run")} ${c.cyan("kaizen")} ${c.dim("again.")}`);
484
+ ? ` ${c.dim("Opened in your browser. Install it, then run")} ${c.accent("kaizen")} ${c.dim("again.")}`
485
+ : ` ${c.dim("Open that page to install it, then run")} ${c.accent("kaizen")} ${c.dim("again.")}`);
458
486
  return false;
459
487
  };
460
488
 
@@ -463,7 +491,7 @@ async function noAgent(): Promise<boolean> {
463
491
  if (!cmd) return docs();
464
492
  if (cmd.startsWith("npm ") && !Bun.which("npm")) return docs(c.dim(`${pick.name} installs with npm, which needs Node.js: https://nodejs.org`));
465
493
 
466
- console.log(`\n ${c.dim("Official installer:")} ${c.cyan(cmd)}`);
494
+ console.log(`\n ${c.dim("Official installer:")} ${c.accent(cmd)}`);
467
495
  if (!(await select(`Install ${pick.name} now?`, [
468
496
  { label: "Yes", hint: "run the command above", value: true },
469
497
  { label: "No", hint: "open the docs page instead", value: false },
@@ -478,7 +506,7 @@ async function noAgent(): Promise<boolean> {
478
506
  if (code !== 0 || !bin) {
479
507
  return docs(code !== 0
480
508
  ? `${c.bold("The install did not finish")} ${c.dim(`(exit ${code}).`)}`
481
- : `${c.bold(`${pick.name} installed, but`)} ${c.cyan(pick.cmd)} ${c.bold("is not on PATH yet.")} ${c.dim("Open a new terminal and run kaizen again.")}`);
509
+ : `${c.bold(`${pick.name} installed, but`)} ${c.accent(pick.cmd)} ${c.bold("is not on PATH yet.")} ${c.dim("Open a new terminal and run kaizen again.")}`);
482
510
  }
483
511
  step(`installed ${pick.name}`);
484
512
 
@@ -534,17 +562,40 @@ if (wantSettings) {
534
562
  if (args.has("worktree")) {
535
563
  const [, verb = "", id = ""] = Bun.argv.slice(2).filter((a) => !a.startsWith("-"));
536
564
  const { locate } = await import("./state.ts");
537
- const { startWorktree, landWorktree, adoptWorkspace, linkTerm } = await import("./worktree.ts");
565
+ const { startWorktree, landRun, adoptWorkspace, linkTerm } = await import("./worktree.ts");
538
566
  const state = locate();
539
567
  if (!state || (verb !== "start" && verb !== "land")) { console.log("\n usage: kaizen worktree start|land <run-id>, in a project with .kaizen\n"); process.exit(1); }
540
568
  const project = dirname(state);
541
569
  // Started inside another workspace of the project (a board worktree): the run is placed there.
542
- const r = verb === "start" ? adoptWorkspace(project, id, process.cwd()) ?? startWorktree(project, id) : landWorktree(project, id);
570
+ const r = verb === "start" ? adoptWorkspace(project, id, process.cwd()) ?? startWorktree(project, id) : landRun(project, id, process.env.KAIZEN_TERM);
543
571
  if (r.ok && verb === "start") linkTerm(state, process.env.KAIZEN_TERM, id);
572
+ if ("warn" in r && r.warn) console.log(`\n warning: ${r.warn}`);
544
573
  console.log(r.ok ? `\n ${verb === "start" ? `worktree ready: ${(r as { path: string }).path}` : `landed by ${(r as { how: string }).how}`}\n` : `\n ${r.why}\n`);
545
574
  process.exit(r.ok ? 0 : 1);
546
575
  }
547
576
 
577
+ // A worktree run's second agent. `start` exits 3 for "build here": no board, or none answered.
578
+ if (args.has("handoff")) {
579
+ const [, verb = "", first = ""] = Bun.argv.slice(2).filter((a) => !a.startsWith("-"));
580
+ const { projectFromWorktree } = await import("./worktree.ts");
581
+ const h = await import("./handoff.ts");
582
+ // A worktree holds committed .kaizen spec copies, never the run: always the project's own.
583
+ const state = join(projectFromWorktree(process.cwd()), ".kaizen");
584
+ const usage = () => { console.log('\n usage: kaizen handoff start <run-id> | done | blocked "<reason>"\n'); process.exit(1); };
585
+ if (verb === "start") {
586
+ if (!first) usage();
587
+ const asked = h.request(state, first, process.env.KAIZEN_TERM);
588
+ if (!asked || !(await h.awaitBoard(state, first))) { console.log("\n no board terminal to hand to: build here, in the worktree\n"); process.exit(3); }
589
+ console.log("\n handed off: end your turn, the board wakes you when it ends\n");
590
+ process.exit(0);
591
+ }
592
+ const id = process.env.KAIZEN_RUN_ID;
593
+ if ((verb !== "done" && verb !== "blocked") || !id) usage();
594
+ const why = h.finish(state, id!, verb as "done" | "blocked", verb === "blocked" ? first : undefined);
595
+ console.log(why ? `\n ${why}\n` : `\n handoff ${verb}\n`);
596
+ process.exit(why ? 1 : 0);
597
+ }
598
+
548
599
  // Deleting runs is a job for code with a test, not for an agent with `rm`. Lists by
549
600
  // default; --yes is what deletes.
550
601
  if (args.has("prune")) {
@@ -556,7 +607,7 @@ if (args.has("prune")) {
556
607
  const apply = args.has("--yes");
557
608
  const gone = pruneRuns(state, keep, apply);
558
609
  console.log(gone.length
559
- ? `\n ${apply ? "pruned" : "would prune"} ${gone.length} finished run(s), keeping the newest ${keep}:\n${gone.map((g) => ` ${g.id}${g.rescued ? c.dim(` ${g.rescued} open item(s) ${apply ? "moved" : "to move"} to backlog.md`) : ""}`).join("\n")}\n${apply ? "" : `\n ${c.dim("nothing deleted — run:")} ${c.cyan("kaizen prune --yes")}\n`}`
610
+ ? `\n ${apply ? "pruned" : "would prune"} ${gone.length} finished run(s), keeping the newest ${keep}:\n${gone.map((g) => ` ${g.id}${g.rescued ? c.dim(` ${g.rescued} open item(s) ${apply ? "moved" : "to move"} to backlog.md`) : ""}`).join("\n")}\n${apply ? "" : `\n ${c.dim("nothing deleted — run:")} ${c.accent("kaizen prune --yes")}\n`}`
560
611
  : `\n nothing to prune ${c.dim(`(${keep} finished runs are kept)`)}\n`);
561
612
  process.exit(0);
562
613
  }
@@ -767,7 +818,7 @@ if (upgrade) {
767
818
  if (after !== latest) {
768
819
  console.log(`\n ${c.bold(`could not install kaizen ${latest}`)}`);
769
820
  // npm names a new version before it serves it (its review takes minutes).
770
- console.log(` ${c.dim("npm may still be publishing it: try again in a few minutes, or run")} ${c.cyan(`bunx kaizen-agent@${latest}`)}\n`);
821
+ console.log(` ${c.dim("npm may still be publishing it: try again in a few minutes, or run")} ${c.accent(`bunx kaizen-agent@${latest}`)}\n`);
771
822
  finish(1);
772
823
  }
773
824
  console.log(`\n ${c.bold("Upgraded")} ${c.dim(now)} → ${c.green(after)}\n ${c.dim("Restart Claude Code to pick up any new slash commands.")}\n`);
@@ -776,107 +827,15 @@ if (upgrade) {
776
827
  if (!check && !upgrade) await welcome();
777
828
 
778
829
  async function welcome() {
779
- const rgb = (r: number, g: number, b: number, s: string) =>
780
- `\x1b[38;2;${r};${g};${b}m${s}\x1b[0m`;
781
-
782
- // Fuji: snow on the peak, deepening blue down the slope.
783
- const WORD = [
784
- "██╗ ██╗ █████╗ ██╗███████╗███████╗███╗ ██╗",
785
- "██║ ██╔╝██╔══██╗██║╚══███╔╝██╔════╝████╗ ██║",
786
- "█████╔╝ ███████║██║ ███╔╝ █████╗ ██╔██╗ ██║",
787
- "██╔═██╗ ██╔══██║██║ ███╔╝ ██╔══╝ ██║╚██╗██║",
788
- "██║ ██╗██║ ██║██║███████╗███████╗██║ ╚████║",
789
- "╚═╝ ╚═╝╚═╝ ╚═╝╚═╝╚══════╝╚══════╝╚═╝ ╚═══╝",
790
- ];
791
- const W = 69, C = 34, SNOW = 3;
792
- // One constant slope, three columns per row, all the way down. The rows behind
793
- // the wordmark keep the same rate, so the edge that goes in above the letters
794
- // comes out below them on the same line -- vary it and the cone reads broken.
795
- const H = [1, 4, 7, 10, 13, 16, 19, 22, 25, 28, 31, 34];
796
-
797
- // Anything that would wrap is worse than the smaller thing that fits: the
798
- // mountain needs the full width, the wordmark needs 47, below that use words.
799
- const cols = process.stdout.columns || 80;
800
- const wide = cols >= W + 4;
801
- if (cols < 49) {
802
- console.log(`\n ${c.bold("kaizen")}`);
803
- } else {
804
-
805
- const cell: string[][] = H.map(() => Array(W).fill(" "));
806
- const isWord: boolean[][] = H.map(() => Array(W).fill(false));
807
-
808
- if (wide) {
809
- for (const [i, h] of H.entries()) {
810
- const l = C - h, r = C + h;
811
- if (i < SNOW) { // solid cap
812
- cell[i]![l] = "▄"; cell[i]![r] = "▄";
813
- for (let x = l + 1; x < r; x++) cell[i]![x] = "█";
814
- } else { // slope, drawn as two edges
815
- // Below the wordmark's top row the letters own the middle, so draw an
816
- // edge only where all three of its characters clear them.
817
- const band = i >= H.length - WORD.length;
818
- const gap = Math.floor((W - 45) / 2) - 2;
819
- if (!band || l + 2 < gap) {
820
- cell[i]![l] = "▄"; cell[i]![l + 1] = "█"; cell[i]![l + 2] = "▀";
821
- cell[i]![r - 2] = "▀"; cell[i]![r - 1] = "█"; cell[i]![r] = "▄";
822
- }
823
- }
824
- }
825
- }
826
-
827
- const top = H.length - WORD.length, left = Math.floor((W - 45) / 2);
828
- for (let r = top; r < H.length; r++) // air around the letters
829
- for (let x = left - 2; x < left + 47; x++) if (x >= 0 && x < W) cell[r]![x] = " ";
830
- for (const [r, line] of WORD.entries())
831
- for (const [x, ch] of [...line].entries())
832
- if (ch !== " ") { cell[top + r]![left + x] = ch; isWord[top + r]![left + x] = true; }
833
-
834
- console.log();
835
- for (const [i, row] of cell.entries()) {
836
- if (!wide && i < top) continue; // no mountain to draw, no blank rows
837
- const slope = Math.max(0, i - SNOW) / (H.length - SNOW);
838
- const mountain: [number, number, number] = i < SNOW
839
- ? [255 - i * 8, 255 - i * 5, 255]
840
- : [Math.round(150 - slope * 105), Math.round(190 - slope * 110), Math.round(245 - slope * 80)];
841
-
842
- // With no mountain there is nothing to sit under, so drop its left margin.
843
- const off = wide ? 0 : left;
844
- const chars = row.slice(off), flags = isWord[i]!.slice(off);
845
-
846
- let out = " ", run = "", runWord = flags[0]!;
847
- const flush = () => {
848
- if (!run) return;
849
- const t = (i - top) / (WORD.length - 1);
850
- const col: [number, number, number] = runWord
851
- ? [Math.round(214 - t * 150), Math.round(232 - t * 130), Math.round(255 - t * 45)]
852
- : mountain;
853
- out += rgb(col[0], col[1], col[2], run);
854
- run = "";
855
- };
856
- for (const [x, ch] of chars.entries()) {
857
- if (flags[x] !== runWord) { flush(); runWord = flags[x]!; }
858
- run += ch;
859
- }
860
- flush();
861
- console.log(out.replace(/\s+$/, ""));
862
- }
863
- if (wide) console.log(" " + rgb(38, 66, 130, "▀".repeat(W)));
864
- }
865
-
866
- console.log(`
867
- ${c.bold("改善")} ${c.dim("kaizen — continuous improvement")}
868
-
869
- ${c.dim("A staged workflow for AI agents — code, writing, research, operations:")}
870
- ${c.dim("plan -> you approve -> build -> independent review -> bounded fix loop")}
871
- `);
872
-
830
+ console.log(banner());
831
+ console.log(` ${c.dim("A staged workflow for AI agents: plan, you approve, build, independent review.")}\n`);
873
832
  if (interactive) await anyKey();
874
833
  }
875
834
 
876
835
  // A pause before anything touches the filesystem, and the place to back out.
877
836
  async function anyKey() {
878
837
  const { stdin, stdout } = process;
879
- stdout.write(` ${c.dim("press")} ${c.cyan("enter")} ${c.dim("to install, or")} ${c.cyan("ctrl-c")} ${c.dim("to leave")}`);
838
+ stdout.write(` ${c.dim("Press")} ${c.accent("Enter")} ${c.dim("to install, or")} ${c.accent("Ctrl-C")} ${c.dim("to leave")}`);
880
839
  stdin.setRawMode(true);
881
840
  stdin.resume();
882
841
  await new Promise<void>((resolve) => {
@@ -893,35 +852,12 @@ async function anyKey() {
893
852
  }
894
853
 
895
854
  const repo = await resolveRepo();
896
- const root = await chooseRoot();
897
- const presetChoice = await choosePreset();
855
+ // Global unless asked otherwise; the project and the preset are `kaizen setup`'s questions.
856
+ const root = args.has("--project") ? process.cwd() : home;
857
+ // null means "leave the config alone": answering for the user would overwrite their preset.
858
+ const presetChoice: PresetName | null = presetArg;
898
859
  const targets = found(root);
899
860
 
900
- // null means "leave the config alone": an upgrade or a --yes run never asked, and
901
- // answering "medium" for the user overwrote whatever preset they had chosen.
902
- async function choosePreset(): Promise<PresetName | null> {
903
- if (presetArg) return presetArg;
904
- if (!interactive) return null;
905
-
906
- return select("Choose workflow preset", [
907
- {
908
- label: "Medium (Recommended)",
909
- hint: "balanced — subagents, plan approval, auto-fix high/critical",
910
- value: "medium",
911
- },
912
- {
913
- label: "Low",
914
- hint: "inline & manual — lite runner, inline builder, manual approvals, no auto-fix",
915
- value: "low",
916
- },
917
- {
918
- label: "Ultra",
919
- hint: "autonomous — subagents, auto mode, auto-fix all findings (up to 4 rounds)",
920
- value: "ultra",
921
- },
922
- ]);
923
- }
924
-
925
861
  // ---------------------------------------------------------------- repo
926
862
 
927
863
  // Settings only needs the clone's default config, not a pull.
@@ -988,22 +924,6 @@ async function resolveRepo() {
988
924
  return dest;
989
925
  }
990
926
 
991
- async function chooseRoot() {
992
- if (args.has("--project")) return process.cwd();
993
- if (args.has("--global") || !interactive) return home;
994
- // A project install only means something in a project. Standing in the home
995
- // directory it is the global install under another name; any other folder is
996
- // a project worth installing into, git repository or not.
997
- const cwd = process.cwd();
998
- if (cwd === home) return home;
999
-
1000
- const names = (r: string) => found(r).map((a) => a.name).join(", ");
1001
- return select("Install kaizen for", [
1002
- { label: "Globally", hint: `every project \u2014 ${names(home)}`, value: home },
1003
- { label: "This project only", hint: `${basename(cwd)}/ \u2014 ${names(cwd)}`, value: cwd },
1004
- ]);
1005
- }
1006
-
1007
927
  // ---------------------------------------------------------------- linking
1008
928
 
1009
929
  function dirEntries(sub: string) {
@@ -1107,10 +1027,6 @@ step(
1107
1027
  : wrote ? `linked ${wrote} files into ${into}`
1108
1028
  : `already installed for ${into} ${c.dim("(nothing to change)")}`,
1109
1029
  );
1110
- if (targets.length === 1) {
1111
- console.log(` ${c.dim("Codex, Antigravity, OpenCode, Cursor and Gemini CLI get it too,")}`);
1112
- console.log(` ${c.dim("if their directory exists when you install.")}`);
1113
- }
1114
1030
 
1115
1031
  // Global knowledge reaches plain Claude Code sessions through a SessionStart hook
1116
1032
  // that prints only the lessons matching the project's stack (cli/knowledge.ts).
@@ -1152,7 +1068,7 @@ function installLauncher() {
1152
1068
  const onPath = (process.env.PATH ?? "").split(win ? ";" : ":")
1153
1069
  .some((p) => p.replace(/[\\/]+$/, "").toLowerCase() === binDir.replace(/[\\/]+$/, "").toLowerCase());
1154
1070
  step(onPath
1155
- ? `${c.cyan("kaizen upgrade")} is now on your PATH`
1071
+ ? `${c.accent("kaizen upgrade")} is now on your PATH`
1156
1072
  : `wrote ${tilde(bin)} ${c.dim(`— add ${tilde(binDir)} to PATH to use it`)}`);
1157
1073
  } catch {
1158
1074
  /* a read-only home is not worth failing the install over */
@@ -1202,17 +1118,7 @@ function kaizenAbove() {
1202
1118
  }
1203
1119
 
1204
1120
  if (inProject && !kaizenAbove()) {
1205
- const now = root === process.cwd() || args.has("--init-project")
1206
- ? true
1207
- : interactive
1208
- ? await select(`Set up ${basename(process.cwd())}/ for kaizen now`, [
1209
- // "Not now" leads: the offer now appears in any folder outside home, so the
1210
- // safe answer is the one under the cursor.
1211
- { label: "Not now", hint: "the first /kaizen run will do it", value: false },
1212
- { label: "Yes", hint: "writes .kaizen/ and a CLAUDE.md line so it runs by default", value: true },
1213
- ])
1214
- : false;
1215
- if (now) initProject();
1121
+ if (root === process.cwd() || args.has("--init-project")) initProject();
1216
1122
  } else if (existsSync(kaizenDir)) {
1217
1123
  const drift = specDrift();
1218
1124
  for (const f of drift) copyFileSync(join(repo, "skills/kaizen", f), join(kaizenDir, f));
@@ -1259,20 +1165,12 @@ function writePointer() {
1259
1165
 
1260
1166
  // ---------------------------------------------------------------- done
1261
1167
 
1262
- {
1263
- console.log(`
1264
- ${c.bold("Next")}
1265
- 1 restart Claude Code ${c.dim("— skills load live, slash commands only at session start")}
1266
- 2 ${c.cyan("/kaizen <what you want done>")} ${c.dim("in any project — it sets itself up on first run")}
1267
- 3 ${c.cyan("kaizen setup")} ${c.dim("— settings, the board, and the phone app, any time")}
1268
-
1269
- ${c.dim("/kaizen-help lists every command. kaizen upgrade updates all of this.")}
1270
- `);
1271
- if (interactive && !blocked && await select("Run setup now?", [
1272
- { label: "Not now", hint: "kaizen setup runs it later", value: false },
1273
- { label: "Yes", hint: "a project folder, settings, the board, the phone", value: true },
1274
- ])) await runSetup();
1275
- }
1168
+ // Setup ends by printing the next steps itself.
1169
+ if (interactive && !blocked && await select("Set up kaizen now? It takes about a minute.", [
1170
+ { label: "Yes", hint: "your project, how much kaizen asks you, the Kaizen App", value: true },
1171
+ { label: "Later", hint: "run kaizen setup any time", value: false },
1172
+ ])) await runSetup();
1173
+ else console.log(nextSteps());
1276
1174
  if (blocked) process.exit(1);
1277
1175
 
1278
1176
  // ---------------------------------------------------------------- helpers
@@ -1407,14 +1305,17 @@ async function select<T>(question: string, options: { label: string; hint: strin
1407
1305
  if (!first) stdout.write(`\x1b[${options.length}A`);
1408
1306
  for (const [i, o] of options.entries()) {
1409
1307
  const on = i === active;
1308
+ // A wrapped row would break the redraw, which moves up one line per option.
1309
+ const room = Math.max(0, (stdout.columns || 80) - o.label.length - 9);
1310
+ const hint = o.hint.length > room ? `${o.hint.slice(0, Math.max(0, room - 1))}…` : o.hint;
1410
1311
  stdout.write(
1411
- `\x1b[2K ${on ? c.cyan(">") : " "} ${on ? c.bold(o.label) : c.dim(o.label)}` +
1412
- ` ${c.dim(o.hint)}\n`,
1312
+ `\x1b[2K ${on ? c.bold(">") : " "} ${on ? c.bold(o.label) : c.dim(o.label)}` +
1313
+ ` ${c.dim(hint)}\n`,
1413
1314
  );
1414
1315
  }
1415
1316
  };
1416
1317
 
1417
- stdout.write(`\n ${c.bold(question)} ${c.dim("(arrows, enter)")}\n`);
1318
+ stdout.write(`\n ${c.bold(question)}\n ${c.dim("Up and down to move, Enter to choose")}\n`);
1418
1319
  stdout.write("\x1b[?25l");
1419
1320
  draw(true);
1420
1321
  stdin.setRawMode(true);
@@ -1430,7 +1331,7 @@ async function select<T>(question: string, options: { label: string; hint: strin
1430
1331
  const keys = chunk.toString();
1431
1332
  for (let i = 0; i < keys.length; i++) {
1432
1333
  const rest = keys.slice(i);
1433
- if (rest.startsWith("\x03")) { stdout.write("\ncancelled\n"); process.exit(130); }
1334
+ if (rest.startsWith("\x03")) { stdout.write("\x1b[?25h\ncancelled\n"); process.exit(130); }
1434
1335
  if (rest.startsWith("\r") || rest.startsWith("\n")) {
1435
1336
  stdin.off("data", onData);
1436
1337
  return resolve();
package/cli/look.ts ADDED
@@ -0,0 +1,33 @@
1
+ // How the installer and `kaizen setup` look: the current monochrome brand. Emphasis is
2
+ // bold, not a colour, so it follows the terminal's own theme, light or dark, as the
3
+ // board's default palette does (design.md, section 2). Green stays for success.
4
+ export const c = {
5
+ dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
6
+ bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
7
+ accent: (s: string) => `\x1b[1m${s}\x1b[0m`,
8
+ green: (s: string) => `\x1b[32m${s}\x1b[0m`,
9
+ };
10
+
11
+ // The pixel K of site/media/favicon.svg, drawn in half blocks so its squares stay square.
12
+ const K = ["█ ▄▀", "██ ", "█ ▀▄"];
13
+
14
+ // Compact block wordmark (27 columns x 3 rows).
15
+ export const WORDMARK = [
16
+ "█ █ ▄▀█ █ ▀▀█ █▀▀ █▄ █",
17
+ "█▀▄ █▀█ █ ▄▀ ██▄ █ ▀█",
18
+ "█ █ █ █ █ █▄▄ █▄▄ █ █",
19
+ ];
20
+
21
+ export function banner() {
22
+ return `\n${K.map((row) => ` ${c.bold(row)}`).join("\n")}\n\n ${c.bold("改善")} ${c.dim("continuous improvement")}\n`;
23
+ }
24
+
25
+ export function nextSteps() {
26
+ return `
27
+ ${c.bold("You're ready")}
28
+ 1 Restart Claude Code ${c.dim("so it picks up the new commands")}
29
+ 2 Ask for something: ${c.accent("/kaizen <what you want done>")}
30
+
31
+ ${c.dim("Change anything later:")} ${c.accent("kaizen setup")}${c.dim(". Every command:")} ${c.accent("/kaizen-help")}
32
+ `;
33
+ }