kaizen-agent 1.22.0 → 1.23.0

package/README.md

@@ -49,6 +49,20 @@ Then, in any project:
 
 That's it. No init and no config.
 
+kaizen needs an AI coding agent to run it, such as [Claude Code](https://docs.claude.com/en/docs/claude-code); install one first. Git is needed for the board's commit and push.
+
+## Use it
+
+There are three ways in, all on the same runs:
+
+| | How | What you do there |
+|---|---|---|
+| **Your agent** | `/kaizen <request>` in Claude Code, Codex, Cursor, … | Start a run and answer it in the chat. All commands are under [Commands](#commands). |
+| **The board** | `kaizen web` opens it in the browser; `kaizen` in a terminal. `kaizen web --shortcut` once adds a launcher: Spotlight on macOS, the app menu on Linux, a Desktop shortcut on Windows | Every project's ideas and runs. Start a run, approve or revise a plan, answer its questions, pick findings to fix, then commit and push. |
+| **Kaizen Bot** | The [desktop app](#download-the-app), or `bun start` in `bot/` | Chat with the board: ask what's waiting on you, hand teammates their asks. The app starts the board itself; from `bot/`, run `kaizen web` first. See [Kaizen Bot](#kaizen-bot). |
+
+Settings for a project or for all of them: `kaizen settings`. New version: `kaizen upgrade`.
+
 ## See it
 
 ```

package/cli/install.test.ts

@@ -90,7 +90,7 @@ const fromPackage = (make: (k: string) => void, custom = false) => {
   const root = mkdtempSync(join(tmpdir(), "kz-replace-"));
   const home = join(root, "home"), pkg = join(root, "pkg");
   const k = custom ? join(root, "kaizen") : join(home, "kaizen");
-  mkdirSync(home);
+  mkdirSync(join(home, ".claude"), { recursive: true });   // an agent: the installer stops on a box with none
   const src = dirname(dirname(import.meta.path));
   for (const d of ["cli", "skills", "agents", "commands", "web", "package.json"]) {
     cpSync(join(src, d), join(pkg, d), { recursive: true, filter: (p) => !p.includes("node_modules") });
@@ -129,7 +129,7 @@ it.skipIf(!Bun.which("git"))("an npm package never replaces a development checko
 it("upgrade with npm unreachable says not upgraded, never up to date", () => {
   const root = mkdtempSync(join(tmpdir(), "kz-offline-"));
   const home = join(root, "home");
-  mkdirSync(home);
+  mkdirSync(join(home, ".claude"), { recursive: true });   // an agent: the installer stops on a box with none
   kaizenFiles(join(home, "kaizen"));
   const env = { PATH: process.env.PATH ?? "", HOME: home, TMPDIR: root, HTTPS_PROXY: "http://127.0.0.1:9", https_proxy: "http://127.0.0.1:9" };
   const p = Bun.spawnSync([process.execPath, script, "upgrade"], { cwd: home, env });

package/cli/notes.test.ts

@@ -71,11 +71,11 @@ test("list: recursive, newest first, dot folders skipped", () => {
 test("list: only names the notebook can save back; a symlinked folder once, never a loop", () => {
   const n = join(state, "notes");
   saveNote(state, "ok", "x", 0);
-  writeFileSync(join(n, "What?.md"), "x");
-  writeFileSync(join(n, "a: b.md"), "x");
+  // Windows refuses these names outright, so there is nothing to list.
+  if (process.platform !== "win32") { writeFileSync(join(n, "What?.md"), "x"); writeFileSync(join(n, "a: b.md"), "x"); }
   mkdirSync(join(n, "1/2/3/4/5/6"), { recursive: true }); writeFileSync(join(n, "1/2/3/4/5/6/deep.md"), "x");
   mkdirSync(join(n, "trail ")); writeFileSync(join(n, "trail ", "x.md"), "x");
-  symlinkSync("..", join(n, "up"));
+  symlinkSync(process.platform === "win32" ? dirname(n) : "..", join(n, "up"), "junction");   // a junction needs no admin
   expect(listNotes(state).map((x) => x.name)).toEqual(["ok"]);
 });
 

package/cli/settings.ts

@@ -117,6 +117,7 @@ const SETTINGS: Setting[] = [
   { key: "dictation.model", label: "Dictation model", group: "Board", values: ["tiny", "base", "small", "large-v3-turbo"], help: "Whisper model the web board dictates with, in the browser. tiny ~60 MB rough; base ~165 MB English-leaning; small ~410 MB accurate across languages; large-v3-turbo ~1.5 GB best, needs a capable GPU. Downloaded once on the next mic press" },
   { key: "sources.every", label: "Gather requests", group: "Board", values: ["off", "1h", "6h", "24h"], help: "How often the board checks your request sources for new ideas while it is running. off: only when you press Gather now" },
   { key: "board.projects_dir", label: "Projects folder", group: "Board", values: [], text: true, folder: true, help: `A folder your projects live in, e.g. ${process.platform === "win32" ? join(homedir(), "Projects") : "~/Projects"}. Every folder inside it appears in the board's project list, ready to choose; choosing one sets it up. Empty: only projects kaizen already knows` },
+  { key: "board.open", label: "Open the board in", group: "Board", values: ["browser", "app"], help: "browser: a tab in your default browser. app: a Chrome, Edge or Brave window with no tabs or address bar, like a desktop app; your default browser when none is installed" },
   { key: "ui.mouse", label: "Enable mouse", group: "Terminal", values: ["false", "true"], help: "Click to select, click again to act. While on, the terminal cannot select text with the mouse" },
 ];
 

package/cli/sources.test.ts

@@ -498,11 +498,12 @@ test("gather everything: each source's ideas land in its own project and no othe
 // The real server, in a scratch home on its own port. Nothing is fetched: only add, list and move.
 test("the board refuses to add a source without a project, and moves one between two", async () => {
   const homeDir = join(root, "home" + n), a = join(homeDir, "a", ".kaizen"), b = join(homeDir, "b", ".kaizen");
-  for (const d of [a, b, join(homeDir, ".kaizen")]) mkdirSync(d, { recursive: true });
+  // ~/.claude: kaizen will not start on a machine with no agent, and a CI box has none.
+  for (const d of [a, b, join(homeDir, ".kaizen"), join(homeDir, ".claude")]) mkdirSync(d, { recursive: true });
   writeFileSync(join(homeDir, ".kaizen", "projects"), [join(homeDir, "a"), join(homeDir, "b")].join("\n") + "\n");
   const port = 20000 + Math.floor(Math.random() * 20000);
   const repo = join(import.meta.dir, "..");
-  const proc = Bun.spawn([process.execPath, join(repo, "cli", "install.ts"), "web", "--port", String(port), "--no-open"], {
+  const proc = Bun.spawn([process.execPath, join(repo, "cli", "install.ts"), "web", "--port", String(port), "--no-open", "--foreground"], {
     cwd: join(homeDir, "a"), env: { ...process.env, HOME: homeDir, USERPROFILE: homeDir, KAIZEN_HOME: repo }, stdout: "ignore", stderr: "ignore",
   });
   try {
@@ -530,4 +531,4 @@ test("the board refuses to add a source without a project, and moves one between
     expect(await post({ op: "add", dir: b, url: SHEET })).toMatchObject({ status: 200 });
     expect(await post({ op: "move", dir: b, to: a, url: SHEET })).toMatchObject({ status: 409, error: "that project already has this link" });
   } finally { proc.kill(); await proc.exited; }
-});
+}, 30_000);   // a cold board start is slow on Windows

package/cli/state.test.ts

@@ -399,6 +399,8 @@ test("commitPush: commits the run's files only, pushes, and records it; the mess
   expect(readCommit(st, "r1")).toEqual({ sha: r.sha, pushed: true });
   expect(cardsGit(st, ["r1", "r0", "nope"])).toEqual({ r1: "pushed", r0: "pushed" });   // r0: no record, but its file is in; c.txt still changed is not its business
 
+  // Windows has no file named b*.txt, so the rest is for everywhere else.
+  if (process.platform === "win32") return;
   // A push that fails leaves a record that says so.
   sh(proj, "remote", "set-url", "origin", join(root, "gone.git"));
   // A fix round's report names files too, and a name with a star in it is not a pattern.
@@ -415,7 +417,7 @@ test("commitPush: commits the run's files only, pushes, and records it; the mess
   expect(runGit(st, "r1")).toMatchObject({ files: [], ahead: 1, others: 2 });
   expect(cardsGit(st, ["r1"])).toEqual({ r1: "pending" });   // committed, not pushed
   expect(cardsGit(join(root, ".kaizen"), ["r1"])).toEqual({});   // not a repo
-});
+}, 60_000);   // dozens of git calls, ~250ms each on Windows
 
 test.skipIf(process.platform === "win32")("findTerminal: a running herdr wins, then tmux, else neither; the prompt stays one literal argument", () => {
   const bin = mkdtempSync(join(tmpdir(), "kz-bin-"));
@@ -427,11 +429,11 @@ test.skipIf(process.platform === "win32")("findTerminal: a running herdr wins, t
     for (const k of keys.slice(1)) delete process.env[k];
     const prompt = `/kaizen it's "q" $HOME \`id\`\n\nnote`;
     const full = ["/usr/bin/claude", "--model", "opus", prompt];
-    expect(findTerminal("/p", full)?.cmd[0]).not.toMatch(/^(sh|tmux)$/);   // neither installed
+    expect(findTerminal("/p", full)?.cmd[0] ?? "none").not.toMatch(/^(sh|tmux)$/);   // neither installed (none: no terminal, as on CI)
     stub("herdr", 1); stub("tmux", 1);
-    expect(findTerminal("/p", full)?.cmd[0]).not.toMatch(/^(sh|tmux)$/);   // installed, no server
+    expect(findTerminal("/p", full)?.cmd[0] ?? "none").not.toMatch(/^(sh|tmux)$/);   // installed, no server
     process.env.TMUX = "/tmp/x,1,0"; process.env.HERDR_ENV = "1";
-    expect(findTerminal("/p", full)?.cmd[0]).not.toMatch(/^(sh|tmux)$/);   // stale env from a server since stopped
+    expect(findTerminal("/p", full)?.cmd[0] ?? "none").not.toMatch(/^(sh|tmux)$/);   // stale env from a server since stopped
     delete process.env.TMUX; delete process.env.HERDR_ENV; stub("tmux", 0);
     const t = findTerminal("/p", full)!;                                   // outside it, server up
     expect(t.cmd.slice(0, 4)).toEqual(["tmux", "new-window", "-c", "/p"]);
@@ -456,8 +458,29 @@ test("nativePath on Windows reads the spellings Git Bash writes into the project
     for (const p of ["/c/Users/me/proj", "C:/Users/me/proj", "c:\\Users\\me\\proj\\", "C:\\Users\\me\\proj"])
       expect(nativePath(p)).toBe("C:\\Users\\me\\proj");
     expect(nativePath("/d")).toBe("D:\\");
+    Object.defineProperty(process, "platform", { value: "linux" });
+    expect(nativePath("/c/Users/me")).toBe("/c/Users/me");   // elsewhere a path is left alone
   } finally { Object.defineProperty(process, "platform", platform); }
-  expect(nativePath("/c/Users/me")).toBe("/c/Users/me");   // elsewhere a path is left alone
+});
+
+test("findTerminal on macOS opens $TERMINAL as an app; iTerm through a script", () => {
+  const keys = ["PATH", "TERMINAL", "TMUX", "HERDR_ENV"];
+  const saved = keys.map((k) => process.env[k]);
+  const platform = Object.getOwnPropertyDescriptor(process, "platform")!;
+  try {
+    Object.defineProperty(process, "platform", { value: "darwin" });
+    process.env.PATH = mkdtempSync(join(tmpdir(), "kz-empty-"));
+    delete process.env.TMUX; delete process.env.HERDR_ENV;
+    process.env.TERMINAL = "Ghostty";
+    expect(findTerminal("/p", ["claude", "x"])!.cmd).toEqual(["open", "-na", "Ghostty", "--args", "--working-directory=/p", "-e", "claude", "x"]);
+    process.env.TERMINAL = "iTerm";
+    const i = findTerminal("/p", ["claude", "x"])!;
+    expect(i.cmd[2]).toContain('create window with default profile command');
+    expect(i.cmd.slice(4)).toEqual(["'/p'", "'claude' 'x'"]);
+  } finally {
+    Object.defineProperty(process, "platform", platform);
+    keys.forEach((k, i) => (saved[i] === undefined ? delete process.env[k] : (process.env[k] = saved[i])));
+  }
 });
 
 test("findTerminal on Windows names cmd and PowerShell by full path, so a PATH without System32 still launches", () => {
@@ -474,7 +497,9 @@ test("findTerminal on Windows names cmd and PowerShell by full path, so a PATH w
     expect(t.cmd[6]).toBe("D:\\Win\\System32\\WindowsPowerShell\\v1.0\\powershell.exe");
     process.env.ComSpec = "E:\\cmd.exe";
     expect(findTerminal("C:\\p", ["claude"])!.cmd[0]).toBe("E:\\cmd.exe");
-    // A running herdr: a tab, and the run typed into it as one encoded line.
+    // A running herdr: a tab, and the run typed into it as one encoded line. The fake
+    // is a shell script, which real Windows cannot run with ComSpec pointed elsewhere.
+    if (platform.value === "win32") return;
     writeFileSync(join(process.env.PATH, "herdr"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
     const h = findTerminal("C:\\p", ["claude", "/kaizen it's\nnote"])!;
     expect([h.cmd[0], h.cmd[1], h.cmd[2], h.detached]).toEqual(["D:\\Win\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", "-NoProfile", "-EncodedCommand", false]);
@@ -815,13 +840,14 @@ test("trustFolder: marks the repo root trusted in a temp config, keeps the rest,
   mkdirSync(sub, { recursive: true }); mkdirSync(plain);
   Bun.spawnSync(["git", "init", "-q", repo]);
   const cfg = join(t, ".claude.json");
-  writeFileSync(cfg, JSON.stringify({ keep: 1, projects: { [plain]: { x: 2 } } }));
+  const key = (p: string) => process.platform === "win32" ? p.replace(/\\/g, "/") : p;   // Claude Code's spelling
+  writeFileSync(cfg, JSON.stringify({ keep: 1, projects: { [key(plain)]: { x: 2 } } }));
   trustFolder(sub, cfg);
   trustFolder(plain, cfg);
   const d = JSON.parse(readFileSync(cfg, "utf8"));
   expect(d.keep).toBe(1);
-  expect(d.projects[realpathSync(repo)]).toEqual({ hasTrustDialogAccepted: true });
-  expect(d.projects[plain]).toEqual({ x: 2, hasTrustDialogAccepted: true });
+  expect(d.projects[key(realpathSync.native(repo))]).toEqual({ hasTrustDialogAccepted: true });
+  expect(d.projects[key(plain)]).toEqual({ x: 2, hasTrustDialogAccepted: true });
   writeFileSync(cfg, "{bad");
   trustFolder(plain, cfg);
   expect(readFileSync(cfg, "utf8")).toBe("{bad");

package/cli/state.ts

@@ -2,7 +2,7 @@
 // `.kaizen/` directory. No terminal, no HTTP: the TUI (`dashboard.ts`) and the web
 // board (`web.ts`) both import this and draw it their own way.
 import { existsSync, readFileSync, readdirSync, appendFileSync, writeFileSync, mkdirSync, statSync, realpathSync, rmSync, renameSync, copyFileSync } from "node:fs";
-import { join, dirname, win32 } from "node:path";
+import { join, dirname, win32, posix } from "node:path";
 import { homedir, arch, cpus, release, totalmem, version as osVersion } from "node:os";
 
 // The real path: process.cwd() is always physical, so a raw $HOME that crosses a
@@ -210,13 +210,26 @@ if ($o -match '"pane_id":"([^"]*)"') { & ${q(herdr)} pane run $Matches[1] ${q(ty
     return { cmd: ["tmux", "new-window", "-c", cwd, ...fullCmd], detached: false };
   }
 
-  if (process.env.TERMINAL && Bun.which(process.env.TERMINAL)) {
-    const term = process.env.TERMINAL;
-    if (term.includes("kitty")) return { cmd: [term, "--directory", cwd, ...fullCmd], detached: true };
-    if (term.includes("alacritty")) return { cmd: [term, "--working-directory", cwd, "-e", ...fullCmd], detached: true };
-    if (term.includes("ghostty")) return { cmd: [term, `--working-directory=${cwd}`, "-e", ...fullCmd], detached: true };
-    if (term.includes("foot")) return { cmd: [term, "-D", cwd, ...fullCmd], detached: true };
-    return { cmd: [term, "-e", ...fullCmd], detached: true };
+  // $TERMINAL: a command on PATH, or on macOS an app's name (TERMINAL=Ghostty, iTerm).
+  const term = process.env.TERMINAL;
+  if (term) {
+    const t = term.toLowerCase();
+    const args = t.includes("kitty") ? ["--directory", cwd, ...fullCmd]
+      : t.includes("alacritty") ? ["--working-directory", cwd, "-e", ...fullCmd]
+      : t.includes("ghostty") ? [`--working-directory=${cwd}`, "-e", ...fullCmd]
+      : t.includes("wezterm") ? ["start", "--cwd", cwd, "--", ...fullCmd]
+      : t.includes("foot") ? ["-D", cwd, ...fullCmd]
+      : ["-e", ...fullCmd];
+    if (process.platform !== "darwin") { if (Bun.which(term)) return { cmd: [term, ...args], detached: true }; }
+    else if (t.includes("iterm")) {
+      // iTerm takes a command line, not argv: the line goes into a one-shot script, as
+      // with Terminal below, and iTerm runs `sh <path>`.
+      const script = `f=$(mktemp) && printf 'rm -f "$0"\\n{ cd %s || (exit 127); } && %s\\n${hold}\\n' "$1" "$2" > "$f" && osascript -e "tell application \\"iTerm\\" to create window with default profile command \\"sh $f\\"" -e 'tell application "iTerm" to activate'`;
+      return { cmd: ["/bin/sh", "-c", script, "sh", shq(cwd), line], detached: true };
+    }
+    // On macOS a terminal is an app, started through open (Ghostty's binary cannot open
+    // a window itself). -n: a new instance, so the args reach it when it is already open.
+    else return { cmd: ["open", "-na", term, "--args", ...args], detached: true };
   }
 
   if (hasDisplay && Bun.which("xdg-terminal-exec")) {
@@ -730,11 +743,12 @@ export function appendNote(state: string, target: { id: string } | { text: strin
 // ponytail: no dedupe, no size accounting beyond the request cap in web.ts.
 export function saveAttachment(state: string, id: string | null, name: string, bytes: Uint8Array) {
   const safe = name.replace(/[^\w.-]+/g, "_").replace(/^\.+/, "") || "file";
-  const rel = id ? join("runs", id, "attachments") : "attachments";
+  // posix: the note links it as attachments/..., and a backslash on Windows breaks that.
+  const rel = id ? posix.join("runs", id, "attachments") : "attachments";
   mkdirSync(join(state, rel), { recursive: true });
   const file = `${Date.now().toString(36)}-${safe}`;
   writeFileSync(join(state, rel, file), bytes);
-  return join(rel, file);
+  return posix.join(rel, file);
 }
 
 // What a card is worth interrupting someone for, in the words both UIs send: a run
@@ -1133,7 +1147,9 @@ export function sessionLaunch(projectDir: string, cmd: string, base: string[], p
 export function trustFolder(dir: string, cfg = join(process.env.CLAUDE_CONFIG_DIR ?? homedir(), ".claude.json")) {
   try {
     const top = Bun.spawnSync(["git", "-C", dir, "rev-parse", "--show-toplevel"], { stderr: "ignore" });
-    const root = top.success ? top.stdout.toString().trim() || dir : dir;
+    // Claude Code keys its projects with forward slashes on Windows, as git prints them.
+    const found = top.success ? top.stdout.toString().trim() || dir : dir;
+    const root = process.platform === "win32" ? found.replace(/\\/g, "/") : found;
     const d = JSON.parse(readFileSync(cfg, "utf8"));
     if (d.projects?.[root]?.hasTrustDialogAccepted) return;
     d.projects ??= {};

package/cli/web.ts

@@ -676,6 +676,11 @@ export async function web(repoDir: string, opts: Opts = {}) {
 // A profile folder gives the window a browser instance of its own (Kaizen Bot's app);
 // on macOS that takes -n, as `open` otherwise hands the args to a running browser.
 export async function openApp(url: string, profile?: string) {
+  // Kaizen Bot's window (a profile) is always an app; the board asks the setting.
+  if (!profile) {
+    const { listSettings } = await import("./settings.ts");
+    if (listSettings(join(import.meta.dir, "..")).rows.find((r) => r.key === "board.open")?.value !== "app") return openDefault(url);
+  }
   const args = [`--app=${url}`, ...(profile ? [`--user-data-dir=${profile}`] : [])];
   const chromes = process.platform === "darwin"
     ? ["Google Chrome", "Chromium", "Microsoft Edge", "Brave Browser"]
@@ -697,6 +702,10 @@ export async function openApp(url: string, profile?: string) {
       }
     }
   } catch { /* fall through to a plain tab */ }
+  return openDefault(url);
+}
+
+async function openDefault(url: string) {
   // `start` is a cmd builtin, not a program, so it has to go through cmd.
   if (process.platform === "win32") {
     try { await Bun.$`${cmdExe()} /c start "" ${url}`.quiet(); return true; } catch { return false; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Staged workflow for AI agents — code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {

package/skills/kaizen/config.default.yml

@@ -178,6 +178,9 @@ board:
   # not itself a project (no .git, no package.json) is read as a group, and the
   # folders inside it are offered too.
   projects_dir: ""
+  # Where `kaizen web` opens the board: browser (a tab in your default browser) or
+  # app (a Chrome, Edge or Brave window with no tabs or address bar).
+  open: browser
 
 sources:
   # How often the web board checks your request sources (links added in the board's