perchai-cli 2.4.115 → 2.4.117

package/README.md

@@ -1,5 +1,8 @@
 # Perch CLI
 
+Version 2.4.116 adds Kimi K3.1 Pro as a Pro model, right after GPT-6.1 Sol
+(`/model kimi-3.1-pro`).
+
 Version 2.4.112 adds MiniMax M3.1 Flash to Starter for a limited time
 (`/model minimax-m3.1-flash-starter`).
 
@@ -37,7 +40,7 @@ perch ap packet ./01-ap
 
 `perch login` opens your browser, completes OAuth through Perch, and saves the CLI session in the macOS Keychain or `~/.perch/cli-auth-session.json` on other platforms.
 
-Interactive mode restores your last persona, mode, permission, model/tier, effort, sub-agent model, and local-tools choices from `~/.perch/cli-settings.json`. MCP servers configured in `~/.perch/mcp.json` or `<workspace>/.perch/mcp.json` are available as CLI tools; the Playwright/browser MCP remains Desktop-only.
+Interactive mode restores your last persona, mode, permission, model/tier, effort, sub-agent model, local-tools, and theme choices from `~/.perch/cli-settings.json`. MCP servers configured in `~/.perch/mcp.json` or `<workspace>/.perch/mcp.json` are available as CLI tools; the Playwright/browser MCP remains Desktop-only.
 
 ## Interactive Commands
 
@@ -53,6 +56,7 @@ Run `perch`, then use these commands inside the terminal chat:
 - `/persona [saffron|quill]` — show or change persona.
 - `/context` — show context meter and compaction details.
 - `/local-tools [on|off]` — show or toggle local shell/file tools.
+- `/theme [auto|dark|light]`: show or set the colors (see Colors below).
 - `/thread [new|id]` — show, reset, or set the current thread id.
 - `/clear` — clear local conversation memory for this terminal session.
 - `/login` — sign in through browser OAuth.
@@ -85,6 +89,34 @@ Replies render as Markdown in an interactive terminal: headings, bold and italic
 - `PERCH_CLI_MARKDOWN=0` shows replies as raw text.
 - `PERCH_CLI_HYPERLINKS=1` makes link text clickable (OSC 8) in any terminal; `0` turns it off. By default it is on for iTerm2, WezTerm, kitty, ghostty, Warp, VS Code, Windows Terminal, and recent VTE terminals, and off inside tmux and screen. The URL is always printed next to the link text.
 
+## Colors
+
+Perch matches your terminal's background. As it starts, it asks the terminal for its background color (most answer within a few milliseconds; Perch never waits more than 150 ms) and uses its light colors on a light background and its dark colors otherwise. On Windows, inside tmux or screen, or when the terminal does not answer, it goes by `COLORFGBG`, else dark; on a light Windows terminal, run `/theme light` once.
+
+- `/theme` shows the setting and what Perch found. `/theme light`, `/theme dark`, or `/theme auto` switches at once and is saved; the same choice is a row in `/settings`.
+- `NO_COLOR` (any value) or `TERM=dumb` turns colors off, whatever the theme.
+
+## herdr
+
+Run `perch` in a [herdr](https://herdr.dev) pane and herdr shows what Perch is doing: working while a turn runs, blocked while it waits for your approval, a plan approval, or an answer to a question, and idle when the message box is ready. Nothing to set up: Perch reports only when herdr starts it (`HERDR_ENV=1`), and does nothing in any other terminal.
+
+Each report also tells herdr how to reopen the chat: `perch --thread <id> --permission <mode>`, the same thread in the same permission mode. That part is left out when no `perch` command is on your `PATH`. Quitting with `/exit`, `Ctrl-D`, or `Ctrl-C` twice hands the pane back to herdr. Only interactive `perch` reports; `perch run` and `perch acp` do not.
+
+## Use Perch in other apps (ACP)
+
+Perch speaks the [Agent Client Protocol](https://agentclientprotocol.com), so apps that run coding agents (Zed, JetBrains IDEs, T3 Code) can use it as their agent.
+
+- **From the ACP Registry:** apps that install agents from the registry run `npx perchai-cli@<version> acp` for you.
+- **As a custom agent:** with `perchai-cli` installed, add an agent whose command is `perch acp` (no other arguments). `npx perchai-cli acp` works too.
+
+**Sign in.** The app offers two ways: "Sign in with Google or GitHub" opens your browser, the same as `perch login`; "Sign in from a terminal" runs `perch login` in a terminal. Signing in with `perch login` beforehand also works, since the app and the CLI share the saved session. Until you sign in, a new chat asks you to.
+
+**Permission modes.** The app's mode picker shows the CLI's four modes: Default, Auto Review, Take the Wheel, and Plan. A chat starts in the mode you last chose in `perch` (`/permission`). When Perch needs approval, the app asks: allow once, always allow this session (only for commands and tools that can be allowed that way), or deny. In Plan mode Perch shows the plan and runs it only after you approve.
+
+**What carries over.** Your saved model, effort, persona, and BYOK choices from the CLI apply (`/model`, `/effort`, `perch byok use`). Each chat is a Perch thread in the folder the app opened, and the app can reopen it with its recent messages. Files you attach in the app are read in like `@path` mentions; images are uploaded with the message.
+
+**Not yet.** MCP servers the app passes are ignored (Perch uses `~/.perch/mcp.json` and `<workspace>/.perch/mcp.json`), and background agents are refused, since nothing would receive their result after a reply ends. Chats run one at a time; a second chat waits until the first one's reply is done.
+
 ## Docs
 
 Full CLI architecture and codebase navigation live in the main repo:

package/bin/perch

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+// Perch needs Node 22 or newer. Checked before anything else, in syntax any
+// Node still parses, so an older Node prints one plain line, not a stack trace.
+var perchNodeMajor = Number(String(process.versions.node).split(".")[0]);
+if (!(perchNodeMajor >= 22)) {
+  console.error(
+    "Perch needs Node 22 or newer. You have v" + process.versions.node + ". Update Node at https://nodejs.org",
+  );
+  process.exit(1);
+}
+
 // Raise V8's old-space ceiling before the app starts. A long agent turn retains
 // the whole turn's state in-heap (messages, tool I/O, the render tree); Node's
 // default old-space limit (~2GB on many machines) aborts the process fatally the
@@ -18,7 +28,7 @@
       const { readFileSync, realpathSync } = await import("node:fs");
       const { dirname, join } = await import("node:path");
       const pkg = JSON.parse(
-        readFileSync(join(dirname(realpathSync(process.argv[1] ?? "")), "..", "package.json"), "utf8"),
+        readFileSync(join(dirname(realpathSync(process.argv[1] || "")), "..", "package.json"), "utf8"),
       );
       if (pkg && pkg.version) process.env.PERCH_CLI_VERSION = String(pkg.version);
     } catch {
@@ -28,7 +38,7 @@
 
   const raised =
     process.env.PERCH_CLI_HEAP_REEXEC === "1" ||
-    /--max[-_]old[-_]space[-_]size/.test(process.env.NODE_OPTIONS ?? "");
+    /--max[-_]old[-_]space[-_]size/.test(process.env.NODE_OPTIONS || "");
   if (!raised) {
     const desiredMb = Number(process.env.PERCH_CLI_MAX_OLD_SPACE_MB || 4096);
     if (Number.isFinite(desiredMb) && desiredMb > 0) {