pi-kage 0.4.0 → 0.5.0

package/README.md

@@ -15,12 +15,17 @@ can't collide.
 
 ```bash
 npm install -g pi-kage
+eval "$(kage shell-init)"   # so kage can cd your shell in & out (recommended)
+
 cd my-app
-kage            # 🥷 copy → ../my-app--kage-<ts>, open a fresh pi
-#   ...commit, push, open a PR, quit pi...
-kage finish     # 💨 merge the clone's sessions back, delete the clone
+kage --agent pi   # 🥷 copy → ../my-app--<name>, cd in, open a fresh pi
+#   ...edit · commit · push · open a PR · quit pi...
+kage finish       # 💨 merge pi's session memory back, delete the clone, cd you home
 ```
 
+Launching an agent is optional: bare `kage` just makes the clone and cd's you in — `--agent` (or
+`kage config agent`, or `$KAGE_AGENT`) is what tells kage to start one for you.
+
 Code comes back through git (a PR, or a branch fetch). The agent's session memory comes back through
 its own session store (`~/.pi`, `~/.claude`, or `~/.codex`). kage never copies a working tree back onto
 the origin — that's the whole point.
@@ -47,8 +52,9 @@ npx pi-kage                 # run without installing
 curl -fsSL https://raw.githubusercontent.com/kid7st/kage/main/install.sh | sh
 ```
 
-Requires **git**, [**pi**](https://github.com/earendil-works), and **Node ≥ 18** on your `PATH`.
-kage has no runtime dependencies.
+Requires **git** and **Node ≥ 18** on your `PATH`, plus at least one coding-agent CLI to drive —
+[**pi**](https://github.com/earendil-works) (the default), [**Claude Code**](https://github.com/anthropics/claude-code),
+or [**Codex**](https://github.com/openai/codex). kage itself has no runtime dependencies.
 
 From source:
 
@@ -57,43 +63,60 @@ git clone https://github.com/kid7st/kage
 cd kage && npm install && npm link   # npm install builds bin/kage.mjs from src/
 ```
 
-## Commands
+## Usage
 
 | Command | Run from | What it does |
 |---|---|---|
-| `kage [path] [--name x] [--agent pi\|claude\|codex]` | origin repo | Copy the repo to `../<repo>--<name>` (default `kage-<ts>`), copy in the origin's 5 most recent sessions for that agent (resumable, never replayed), and launch a **fresh** agent (pi by default). `--name` only names the folder — kage never creates a branch. No args + existing clones → interactive menu. |
+| `kage [path] [--name x] [--agent <id>]` | origin repo | Copy the repo to `../<repo>--<name>` (default `kage-<ts>`), import the origin's recent sessions (resumable, never replayed), **cd you into the clone**, and launch an agent only if you named one (`--agent`/`$KAGE_AGENT`/`kage config agent`) — else just drop you in. `--name` only names the folder; kage never creates a branch. No args + existing clones → interactive menu. |
 | `kage status [--pr]` | origin repo | Dashboard: branch, dirty/clean, ahead/behind, "safe to clean". `--pr` adds PR state via `gh`. |
-| `kage finish [name] [--force] [--push] [--pr]` | origin / inside clone | Refuse if the clone has uncommitted or unpushed work, merge its **new** sessions back, delete it. `--push` pushes the branch first; `--pr` pushes + opens a PR via `gh`; `--force` skips the guard. |
+| `kage finish [name] [--force] [--push] [--pr]` | origin / inside clone | Preserve the clone's commits (push, or with no remote a local `kage/<name>` branch), merge its **new** sessions back, delete it, cd you home. Refuses uncommitted changes — and, with a remote, unpushed commits — unless `--force`. `--push`/`--pr` push first (and open a PR via `gh`). |
 | `kage rm [name] [--force]` | origin / inside clone | Discard a clone **without** merging memory. Refuses local-only work unless `--force`. |
 | `kage pull <path...>` | inside a clone | Copy specific files/dirs (even gitignored, e.g. a generated `.env`) back to the origin. |
-| `kage shell-init` | shell rc | Shell wrapper (cd back to origin after `finish`/`rm`) + tab completion. Use `eval "$(kage shell-init)"`. |
+| `kage config [<key> [value]] [--unset]` | anywhere | Get/set persisted defaults. One key today: `agent` (your default launch agent), validated against known agents. |
+| `kage shell-init` | shell rc | Shell wrapper (cd into a clone on create, back to origin on `finish`/`rm`) + tab completion. Use `eval "$(kage shell-init)"`. |
 | `kage --help` / `--version` | anywhere | Usage / version. |
 
 Run bare `kage` inside a repo that already has clones to get an interactive picker: create a new clone,
 or **enter** / **finish** / **remove** an existing one. `finish` and `rm` show the same picker when you
 have several clones and don't name one.
 
-### Other agents (Claude Code, Codex)
+## Agents
+
+kage is agent-agnostic — and launching an agent is **opt-in**. By default `kage` just creates the clone and
+cd's your shell into it; you work however you like. To have kage launch one for you, name it with `--agent`,
+or set a default with `kage config agent` (or `$KAGE_AGENT`) — precedence `--agent` > `$KAGE_AGENT` >
+`kage config agent`; with none set, nothing is launched. Whichever way you work, every agent gets the same
+isolated clone and git flow-back — what differs is **memory flow-back**, i.e. whether the sessions you
+create in the clone come home to the origin:
+
+| Agent | Launch it with | Memory flow-back |
+|---|---|---|
+| **pi** | `kage --agent pi` | ✅ full round-trip — recent sessions copied in on create, new ones merged back on `finish` |
+| **Claude Code** | `kage --agent claude` | ✅ full round-trip (same as pi) |
+| **Codex** | `kage --agent codex` | ⚠️ git only — history stays global, reach it with `codex resume --all` |
+
+**Why Codex is git-only.** pi and Claude Code key their session stores by working directory, so kage can
+copy a clone's sessions over to the origin's directory and back. Codex keeps one global, sqlite-indexed
+store that kage can't cleanly re-home — so `--agent codex` gives you the isolated clone + git flow-back,
+and your Codex history stays globally reachable. Details in
+[`docs/multi-agent-design.md`](./docs/multi-agent-design.md).
+
+You can run several agents at once — a clone each, or different agents in one clone. Each agent uses its
+own store, so they never collide, and `finish` merges back whichever stores gained new sessions.
 
-kage isn't pi-only. `--agent claude` or `--agent codex` launches that agent instead. For **pi and Claude
-Code**, memory flows the same way — through that agent's own session store (whether you drive it from the
-CLI, the IDE extension, or the desktop app), and two agents can even work one repo in parallel (a clone
-each, or different agents in one clone); `finish` merges back whichever stores have new sessions.
-**Codex is launch-only**: its sessions live in one global, sqlite-indexed store kage can't cleanly
-re-home, so `--agent codex` gives you the isolated clone + git flow-back while your Codex history stays
-globally available via `codex resume --all`. For a GUI/desktop app kage can't spawn, use `--open <cmd>`
-(e.g. `kage --open code`) or `--no-launch` to just make the clone and open it yourself. `KAGE_AGENT` sets
-your default agent.
+**Driving a GUI/IDE agent kage can't spawn?** Use `--open <cmd>` to create the clone and open it yourself
+(e.g. `kage --open code` runs `code <clone>`), or `--no-launch` to just make the clone and print its path.
+Memory still flows for any agent whose store kage manages, no matter how you opened the clone.
 
-### Shell integration (optional)
+## Shell integration (recommended)
 
 ```bash
 eval "$(kage shell-init)"   # add to ~/.zshrc or ~/.bashrc
 ```
 
-Running `finish`/`rm` from inside a clone deletes the directory your shell is sitting in. The wrapper
-cd's you back to the origin automatically (a CLI can't change its parent shell otherwise) and adds tab
-completion for subcommands and clone names.
+`kage` cd's your shell **into** the new clone, and `finish`/`rm` cd it **back** to the origin afterward
+(a CLI can't move its parent shell otherwise, so this needs the wrapper — without it, kage just prints the
+`cd` for you to run). It also adds tab completion for subcommands and clone names.
 
 ## How it works
 
@@ -105,11 +128,10 @@ completion for subcommands and clone names.
   `kage/<name>-<sha>` branch (origin working tree untouched — `git merge` it when you like). Because a
   fetch can't preserve uncommitted work, `finish` refuses to delete a dirty clone unless `--force`.
 - **Memory flows via the agent's own session store, never replayed.** On create, the origin's 5 most
-  recent sessions for that agent are copied in — the agent's resume picker surfaces them, but the clone
-  opens a **fresh** session. On `finish`, sessions the clone created come back whole; a copied-in session
-  you resumed comes back as a separate new session, so the origin's original is never mutated. (Codex is the
-  exception — its sessions live in one global, sqlite-indexed store kage can't cleanly re-home, so kage
-  doesn't manage Codex memory; find Codex history with `codex resume --all`. See `docs/multi-agent-design.md`.)
+  recent sessions for that agent are copied in — the agent's resume picker surfaces them when you launch it, but you
+  start a **fresh** session. On `finish`, sessions the clone created come back whole; a copied-in session
+  you resumed comes back as a separate new session, so the origin's original is never mutated. (Codex is
+  the exception — git-only flow-back; see [Agents](#agents).)
 - **The origin is read-only to kage.** It only copies out and writes session memory — it never touches
   the origin's working tree, even while another session is live there.
 

package/README.zh-CN.md

@@ -14,12 +14,17 @@
 
 ```bash
 npm install -g pi-kage
+eval "$(kage shell-init)"   # 让 kage 能 cd 你的 shell 进 / 出（推荐）
+
 cd my-app
-kage            # 🥷 复制 → ../my-app--kage-<ts>，打开一个全新的 pi
-#   ...提交、push、开 PR、退出 pi...
-kage finish     # 💨 把分身的 session 合并回来，删掉分身
+kage --agent pi   # 🥷 复制 → ../my-app--<name>，cd 进去，开一个全新的 pi
+#   ...编辑 · 提交 · push · 开 PR · 退出 pi...
+kage finish       # 💨 把 pi 的 session 记忆合并回来，删掉分身，再把你 cd 回原仓库
 ```
 
+启动 agent 是可选的：纯跑 `kage` 只是建好分身并把你 cd 进去 —— `--agent`（或 `kage config agent`、或
+`$KAGE_AGENT`）才是告诉 kage 替你启动一个的开关。
+
 代码通过 git 回流（一个 PR，或者 fetch 分支）；agent 的 session 记忆通过它自己的 session 存储（`~/.pi`、
 `~/.claude` 或 `~/.codex`）回流。kage 从不把工作区复制回原仓库 —— 这正是它存在的意义。
 
@@ -43,8 +48,9 @@ npx pi-kage                 # 不安装直接运行
 curl -fsSL https://raw.githubusercontent.com/kid7st/kage/main/install.sh | sh
 ```
 
-需要 `PATH` 上有 **git**、[**pi**](https://github.com/earendil-works) 和 **Node ≥ 18**。
-kage 没有任何运行时依赖。
+需要 `PATH` 上有 **git** 和 **Node ≥ 18**，外加至少一个 coding-agent CLI 来驱动 ——
+[**pi**](https://github.com/earendil-works)（默认）、[**Claude Code**](https://github.com/anthropics/claude-code)
+或 [**Codex**](https://github.com/openai/codex)。kage 本身没有任何运行时依赖。
 
 从源码安装：
 
@@ -53,39 +59,56 @@ git clone https://github.com/kid7st/kage
 cd kage && npm install && npm link   # npm install 会从 src/ 编译出 bin/kage.mjs
 ```
 
-## 命令
+## 使用
 
 | 命令 | 在哪运行 | 作用 |
 |---|---|---|
-| `kage [path] [--name x] [--agent pi\|claude\|codex]` | 原仓库 | 把仓库复制到 `../<repo>--<name>`（默认 `kage-<ts>`），拷入原仓库最近 5 个该 agent 的 session（可 resume，绝不重放），并启动一个**全新**的 agent（默认 pi）。`--name` 只命名文件夹 —— kage 从不建分支。无参数 + 已有分身 → 进入交互菜单。 |
+| `kage [path] [--name x] [--agent <id>]` | 原仓库 | 把仓库复制到 `../<repo>--<name>`（默认 `kage-<ts>`），拷入原仓库最近的 session（可 resume，绝不重放），**把你 cd 进分身**，仅当你指定了 agent（`--agent`/`$KAGE_AGENT`/`kage config agent`）才启动它 —— 否则只把你放进去。`--name` 只命名文件夹；kage 从不建分支。无参数 + 已有分身 → 进入交互菜单。 |
 | `kage status [--pr]` | 原仓库 | 仪表盘：分支、是否有改动、ahead/behind、是否「可安全清理」。`--pr` 通过 `gh` 附带 PR 状态。 |
-| `kage finish [name] [--force] [--push] [--pr]` | 原仓库 / 分身内 | 若分身有未提交或未 push 的改动则拒绝，把它**新产生**的 session 合并回来，再删除它。`--push` 先 push 分支；`--pr` push 并通过 `gh` 开 PR；`--force` 跳过检查。 |
+| `kage finish [name] [--force] [--push] [--pr]` | 原仓库 / 分身内 | 先保留分身的 commit（push，或无 remote 时存成原仓库本地分支 `kage/<name>`），把它**新产生**的 session 合并回来，删掉分身，再把你 cd 回原仓库。有未提交改动 —— 以及有 remote 时还有未 push 的 commit —— 则拒绝，除非加 `--force`。`--push`/`--pr` 先 push（并通过 `gh` 开 PR）。 |
 | `kage rm [name] [--force]` | 原仓库 / 分身内 | **不**合并记忆地丢弃一个分身。若有仅存在于本地的工作则拒绝，除非加 `--force`。 |
 | `kage pull <path...>` | 分身内 | 把指定文件/目录（包括被 gitignore 的，比如生成的 `.env`）按相同相对路径拷回原仓库。 |
-| `kage shell-init` | shell 配置 | shell 包装函数（`finish`/`rm` 后自动 cd 回原仓库）+ tab 补全。用 `eval "$(kage shell-init)"`。 |
+| `kage config [<key> [value]] [--unset]` | 任意位置 | 读取/设置持久化默认值。目前只有一个 key：`agent`（默认启动的 agent），会校验是否为已知 agent。 |
+| `kage shell-init` | shell 配置 | shell 包装函数（创建时 cd 进分身，`finish`/`rm` 后 cd 回原仓库）+ tab 补全。用 `eval "$(kage shell-init)"`。 |
 | `kage --help` / `--version` | 任意位置 | 用法 / 版本。 |
 
 在已有分身的仓库里直接运行 `kage`，会弹出交互选择器：新建一个分身，或对已有分身执行 **进入** / **finish** /
 **删除**。当有多个分身又没指定名字时，`finish` 和 `rm` 也会弹出同样的选择器。
 
-### 其它 agent（Claude Code、Codex）
+## Agents
+
+kage 与具体 agent 无关 —— 而且启动 agent 是**可选的**。默认下 `kage` 只创建分身并把你的 shell cd 进去，
+接下来你爱怎么干就怎么干。想让 kage 替你启动一个 agent，就用 `--agent` 指定，或用 `kage config agent`
+（或 `$KAGE_AGENT`）设个默认值 —— 优先级 `--agent` > `$KAGE_AGENT` > `kage config agent`；一个都没设就
+什么都不启动。不管怎么干，每个 agent 都得到同样的隔离分身和 git 回流 —— 区别在于**记忆回流**，也就是
+你在分身里产生的 session 是否会回到原仓库：
+
+| Agent | 怎么启动 | 记忆回流 |
+|---|---|---|
+| **pi** | `kage --agent pi` | ✅ 完整往返 —— 创建时拷入最近的 session，`finish` 时把新产生的合并回来 |
+| **Claude Code** | `kage --agent claude` | ✅ 完整往返（同 pi） |
+| **Codex** | `kage --agent codex` | ⚠️ 仅 git —— 历史保持全局，用 `codex resume --all` 找回 |
+
+**为什么 Codex 只有 git 回流。** pi 和 Claude Code 的 session 存储按工作目录索引，所以 kage 能把分身的
+session 拷到原仓库的目录、再拷回来。Codex 用的是一个由 sqlite 索引的全局 store，kage 无法干净地搬迁 ——
+所以 `--agent codex` 给你隔离分身 + git 回流，而 Codex 历史保持全局可达。详见
+[`docs/multi-agent-design.md`](./docs/multi-agent-design.md)。
+
+你可以同时跑多个 agent —— 各开一个分身，或在同一个分身里换着用。每个 agent 用自己的 store，互不冲突，
+`finish` 会把有新 session 的那些 store 各自合并回来。
 
-kage 不只支持 pi。`--agent claude` 或 `--agent codex` 会改为启动对应 agent。对 **pi 和 Claude Code**，记忆照样
-流动 —— 通过该 agent **自己的** session 存储（无论用 CLI、IDE 扩展还是桌面 App），两个 agent 甚至能并行
-处理同一个仓库（各开一个分身，或同一个分身里换着用）；`finish` 会把有新 session 的那些 store 各自合并回来。
-**Codex 是 launch-only**：它的 session 存在一个由 sqlite 索引的全局 store 里，kage 无法干净地搬迁，所以
-`--agent codex` 给你隔离分身 + git 回流，而 Codex 历史通过 `codex resume --all` 依然全局可见。对于 kage 没法
-直接拉起的 GUI / 桌面 App，用 `--open <cmd>`（比如 `kage --open code`）或 `--no-launch` 只建分身、你自己去打开。
-`KAGE_AGENT` 设置默认 agent。
+**要用 kage 拉不起来的 GUI/IDE agent？** 用 `--open <cmd>` 建好分身后自己打开它（比如 `kage --open code`
+会执行 `code <clone>`），或用 `--no-launch` 只建分身并打印路径。无论你怎么打开分身，只要是 kage 管理其
+store 的 agent，记忆照样回流。
 
-### Shell 集成（可选）
+## Shell 集成（推荐）
 
 ```bash
 eval "$(kage shell-init)"   # 加到 ~/.zshrc 或 ~/.bashrc
 ```
 
-在分身内运行 `finish`/`rm` 会删掉你 shell 当前所在的目录。这个包装函数会自动把你 cd 回原仓库（否则 CLI
-没法改变父 shell 的目录），并为子命令和分身名加上 tab 补全。
+`kage` 会把你的 shell cd **进**新分身，`finish`/`rm` 再把它 cd **回**原仓库（CLI 没法改变父 shell 的目录，
+所以这需要包装函数 —— 没装的话，kage 就只把 `cd` 命令打印出来让你自己跑）。它还为子命令和分身名加上 tab 补全。
 
 ## 工作原理
 
@@ -95,10 +118,9 @@ eval "$(kage shell-init)"   # 加到 ~/.zshrc 或 ~/.bashrc
   分身的分支 fetch 进原仓库的 git，存成本地分支 `kage/<name>-<sha>`（原仓库工作区不动 —— 你想合并时再
   `git merge`）。由于 fetch 无法保留未提交的改动，`finish` 拒绝删除有改动的分身，除非加 `--force`。
 - **记忆经由该 agent 自己的 session 存储回流，绝不重放。** 创建时拷入原仓库最近 5 个该 agent 的 session —— 该
-  agent 的 resume 选择器能看到它们，但分身本身打开的是**全新** session。`finish` 时，分身自己产生的 session 整份
+  agent 的 resume 选择器在你启动它时能看到它们，但你从一个**全新** session 开始。`finish` 时，分身自己产生的 session 整份
   拷回；你 resume 过的拷入 session 会作为一个独立的新 session 回来，原仓库的原始 session 绝不被改动。（Codex 是
-  例外 —— 它的 session 在一个 sqlite 索引的全局 store 里，kage 无法干净搬迁，所以不管理 Codex 记忆；Codex
-  历史用 `codex resume --all` 查。详见 `docs/multi-agent-design.md`。）
+  例外 —— 仅 git 回流；见 [Agents](#agents)。）
 - **对 kage 而言原仓库是只读的。** 它只往外复制、只写 session 记忆 —— 即使原仓库里另有一个 session 正活跃，
   它也绝不碰原仓库的工作区。
 

package/bin/kage.mjs

@@ -2,25 +2,23 @@
 /**
  * kage 🥷 — cast the Shadow Clone Jutsu on a git repo.
  *
- * Copy the current repo into an isolated sibling folder (its own working tree and .git),
- * drop straight into `pi` to work in parallel, then `kage finish` merges the session memory
- * back into the original and deletes the clone.
+ * Copy the current repo into an isolated sibling folder (its own working tree and .git) and cd
+ * into it; optionally launch a coding agent there. `kage finish` merges the agent's session memory
+ * back into the origin and deletes the clone. Run `kage --help` for the command surface.
  *
  * Design invariants:
  *   1. Isolation   — a clone is a full independent copy (its own .git).
  *   2. Code flows back via git only — a remote PR, or (no remote) a fetch of the clone's branch
  *      into the origin's git on finish; kage never copies the working tree back onto the origin.
- *   3. Memory flows via ~/.pi — the origin's session history is copied into the clone on create
+ *   3. Memory flows via each agent's own session store (pi/Claude Code keyed by cwd; Codex is
+ *      launch-only, not kage-managed) — the origin's history is copied into the clone on create
  *      (resumable, never replayed) and the clone's new sessions are merged back on finish. These
- *      are session .jsonl files, not the working tree, so there's no collision.
- *   4. The origin is read-only to kage — it only copies out and writes session memory.
+ *      are session files, not the working tree, so there's no collision.
+ *   4. The origin's working tree is read-only to kage — it only copies out, writes the kage/<name>
+ *      branch into the origin's git (no-remote finish), and writes session memory.
  *
- * Commands:
- *   kage [path] [--name x] [--agent id]              clone repo + launch an agent (no args: interactive)
- *   kage status [--pr]                               dashboard of clones (+ PR status via gh)
- *   kage finish [name] [--force]                     check -> merge memory back -> delete clone
- *   kage rm [name] [--force]                         discard a clone (no merge)
- *   kage pull <path...>                              (inside a clone) copy files back to the origin
+ * Launch is opt-in and detachable (see docs/multi-agent-design.md): with no agent named
+ * (--agent / $KAGE_AGENT / `kage config agent`), kage just creates the clone and cd's you in.
  */
 import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -28,7 +26,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync,
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import readline from "node:readline";
-const VERSION = "0.4.0"; // keep in sync with package.json (enforced by test)
+const VERSION = "0.5.0"; // keep in sync with package.json (enforced by test)
 const MARKER = ".kage.json";
 const RECENT_SESSIONS = 5; // how many of the origin's most-recent sessions to copy into a clone
 /** Typed accessors for the loose flags bag, so consumers don't re-derive the shape inline. */
@@ -86,6 +84,34 @@ function readMarker(dir) {
         return undefined;
     }
 }
+const CONFIG_KEYS = ["agent"];
+function configPath() {
+    const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(base, "kage", "config.json");
+}
+function readConfig() {
+    const p = configPath();
+    if (!existsSync(p))
+        return {};
+    try {
+        const v = JSON.parse(readFileSync(p, "utf8"));
+        if (typeof v !== "object" || v === null)
+            return {};
+        const o = v;
+        const cfg = {};
+        if (typeof o.agent === "string")
+            cfg.agent = o.agent;
+        return cfg;
+    }
+    catch {
+        return {};
+    }
+}
+function writeConfig(cfg) {
+    const p = configPath();
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, `${JSON.stringify(cfg, null, 2)}\n`);
+}
 /** Copy a whole directory: clonefile on macOS, reflink on Linux, plain copy as fallback. */
 function copyTree(src, dst) {
     const isMac = process.platform === "darwin";
@@ -246,6 +272,14 @@ function prInfo(dir, branch) {
 }
 /** True when the clone has no local-only work (clean + pushed) -> safe to remove. */
 const isSafeToClean = (s) => !s.dirty && s.hasUpstream && s.ahead === 0;
+/** Single-glyph clone state, shared by the dashboard and the menu/picker so a clone always reads the
+ *  same: ● uncommitted · ↑ clean but unpushed/local-only · ✓ clean & pushed (safe to remove). */
+const statusTag = (s) => (s.dirty ? paint.yellow("●") : isSafeToClean(s) ? paint.green("✓") : paint.yellow("↑"));
+/** One-line clone label for the menu and the finish/rm picker: name, branch, state tag. */
+function cloneLabel(c) {
+    const s = cloneStatus(c.dir);
+    return `${c.name}  ${paint.cyan(s.branch)} ${statusTag(s)}`;
+}
 /** True if the clone has committed work that lives only in the clone (not on a remote, not yet in the origin). */
 function hasUnpreservedCommits(originRepo, cloneDir, s) {
     if (s.hasUpstream && s.ahead === 0)
@@ -345,7 +379,7 @@ async function pickClone(action, name) {
     const first = clones[0];
     if (first && clones.length === 1)
         return { originRepo, clone: first };
-    const idx = await select(`Multiple clones — pick one to ${action}:`, clones.map((c) => `${c.name}  ${paint.dim(cloneStatus(c.dir).branch)}`));
+    const idx = await select(`Multiple clones — pick one to ${action}:`, clones.map(cloneLabel));
     const chosen = idx < 0 ? undefined : clones[idx];
     if (!chosen)
         return null;
@@ -434,17 +468,18 @@ function dirStore(cfg) {
             try {
                 rmSync(srcDir, { recursive: true, force: true });
             }
-            catch {
-                /* ignore */
+            catch (e) {
+                info(paint.dim(`   (couldn't clear the clone's ${cfg.id} sessions at ${srcDir}: ${e.message})`));
             }
             return n;
         },
         discard(cloneDir) {
+            const d = dirFor(cloneDir);
             try {
-                rmSync(dirFor(cloneDir), { recursive: true, force: true });
+                rmSync(d, { recursive: true, force: true });
             }
-            catch {
-                /* ignore */
+            catch (e) {
+                info(paint.dim(`   (couldn't discard the clone's ${cfg.id} sessions at ${d}: ${e.message})`));
             }
         },
         hasActivity(cwd) {
@@ -599,30 +634,57 @@ const codexStore = {
         return codexRollouts().some((r) => r.cwd === cwd);
     },
 };
-/**
- * We just deleted the clone we were running inside, so the parent shell is now in a
- * deleted directory. A CLI can't cd its parent shell, so: if the shell wrapper is active
- * (KAGE_CD_FILE set by `eval "$(kage shell-init)"`), hand it the origin path to cd into;
- * otherwise print a copy-pasteable `cd` and how to enable the auto version.
- */
-function leaveClone(originRepo) {
+// A CLI can't cd its parent shell. If the shell wrapper is active (KAGE_CD_FILE, set by
+// `eval "$(kage shell-init)"`), hand it a path to cd into once kage exits; otherwise we can only
+// print a copy-pasteable `cd`. armCd does the handoff; leaveClone/cdIntoClone do the messaging.
+function armCd(dir) {
     const f = process.env.KAGE_CD_FILE;
-    if (f) {
-        try {
-            writeFileSync(f, originRepo);
-            info(paint.dim(`   ↩  back to ${originRepo}`));
-            return;
-        }
-        catch {
-            /* fall through to the manual hint */
-        }
+    if (!f)
+        return false;
+    try {
+        writeFileSync(f, dir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const SHELL_INIT_HINT = `add  eval "$(kage shell-init)"  to your ~/.zshrc`;
+/** After deleting the clone we were inside, the parent shell sits in a now-deleted dir — send it
+ *  back to the origin (or print how, without the wrapper). */
+function leaveClone(originRepo) {
+    if (armCd(originRepo)) {
+        info(paint.dim(`   ↩  back to ${originRepo}`));
+        return;
     }
     info(paint.yellow(`   ↩  your shell is still in the deleted clone — run:  ${paint.bold(`cd ${originRepo}`)}`));
-    info(paint.dim(`      enable auto cd-back: add  eval "$(kage shell-init)"  to your ~/.zshrc`));
+    info(paint.dim(`      enable auto cd-back: ${SHELL_INIT_HINT}`));
+}
+/** Settle the shell inside a clone we just created/entered: cd there if the wrapper is active,
+ *  else print a copy-pasteable `cd` + the finish hint. */
+function cdIntoClone(cloneDir, name) {
+    info("");
+    if (armCd(cloneDir)) {
+        info(paint.dim(`   ↪  now in the clone — when done: ${paint.bold("kage finish")}`));
+        return;
+    }
+    info(`   ▸  enter it:  ${paint.bold(`cd ${cloneDir}`)}`);
+    info(paint.dim(`      when done: ${paint.bold(`kage finish ${name}`)}`));
+    info(paint.dim(`      tip: ${SHELL_INIT_HINT} — then kage cd's you in & out automatically`));
+}
+/** chdir the kage process out of a clone it's about to delete (rmSync of the cwd fails otherwise).
+ *  Surfaced rather than swallowed — a silent failure here is why a later rmSync would fail. */
+function chdirToOrigin(originRepo) {
+    try {
+        process.chdir(originRepo);
+    }
+    catch (e) {
+        info(paint.dim(`   (couldn't chdir to ${originRepo}: ${e.message})`));
+    }
 }
 // Registered agents. Memory sync iterates this list, so each new agent is one entry (+ its
-// SessionStore) with no change to any call site. Codex (a flat, cwd-in-content store) lands
-// here in Phase 3.
+// SessionStore) with no change to any call site. Codex is the odd one — a flat, cwd-in-content
+// store that kage doesn't memory-manage (see codexStore).
 const AGENTS = [
     { id: "pi", store: piStore, cli: { bin: "pi", freshArgs: [], resumeArgs: ["-c"] } },
     { id: "claude", store: claudeStore, cli: { bin: "claude", freshArgs: [], resumeArgs: ["--continue"] } },
@@ -652,24 +714,19 @@ function launchOpen(cmd, cwd) {
         die(`failed to run --open ${cmd}: ${err.message}`);
     }
 }
-/** Re-enter a clone: resume whichever agent has activity here (ask if several), else start fresh. */
-async function enterClone(cloneDir) {
+/** Re-enter a clone from the menu: resume an agent that has activity here (ask if several), then
+ *  leave the shell in the clone. With no activity — or if you cancel the resume picker — just cd in;
+ *  kage never auto-launches an agent, and Enter always lands you in the clone. */
+async function enterClone(cloneDir, name) {
     const active = AGENTS.filter((a) => a.cli && a.store.hasActivity(cloneDir));
-    if (active.length === 0) {
-        const def = agentById(process.env.KAGE_AGENT ?? "pi") ?? AGENTS[0];
-        if (def?.cli)
-            launchCli(def.cli, cloneDir, def.cli.freshArgs);
-        return;
-    }
-    let chosen = active[0];
+    let chosen = active[0]; // undefined when nothing has activity here
     if (active.length > 1) {
-        const idx = await select("Resume which agent?", active.map((a) => a.id));
-        if (idx < 0)
-            return info("cancelled");
-        chosen = active[idx];
+        const idx = await select("Resume which agent? (Esc = just cd in)", active.map((a) => a.id));
+        chosen = idx < 0 ? undefined : active[idx]; // cancel → don't resume, but still cd in below
     }
     if (chosen?.cli)
         launchCli(chosen.cli, cloneDir, chosen.cli.resumeArgs);
+    cdIntoClone(cloneDir, name);
 }
 // ── subcommands ───────────────────────────────────────────────────────────────
 async function cmdNew(argv) {
@@ -680,24 +737,22 @@ async function cmdNew(argv) {
         const repoRoot = repoTopLevel(process.cwd());
         const clones = repoRoot ? listClones(repoRoot) : [];
         if (repoRoot && clones.length > 0) {
-            const labels = [
-                "＋ Create a new shadow clone",
-                ...clones.map((c) => {
-                    const s = cloneStatus(c.dir);
-                    const tag = s.dirty ? paint.yellow(" ●") : isSafeToClean(s) ? paint.green(" ✓") : "";
-                    return `→ Enter ${c.name}  ${paint.cyan(s.branch)}${tag}`;
-                }),
-            ];
-            const idx = await select(`Shadow clones of ${basename(repoRoot)} — pick one, or create:`, labels);
+            const labels = ["＋ Create a new clone", ...clones.map(cloneLabel)];
+            const idx = await select(`Shadow clones of ${basename(repoRoot)} — pick one to act on, or create:`, labels);
             if (idx < 0)
                 return info("cancelled");
             if (idx > 0) {
                 const clone = clones[idx - 1];
                 if (!clone)
                     return info("cancelled");
-                const act = await select(`${clone.name}:`, ["Enter (resume)", "Finish (merge memory & remove)", "Remove (discard)", "Cancel"]);
+                const act = await select(`${clone.name}:`, [
+                    "Enter (resume agent + cd in)",
+                    "Finish (merge memory & remove)",
+                    "Remove (discard, no merge)",
+                    "Cancel",
+                ]);
                 if (act === 0)
-                    return enterClone(clone.dir);
+                    return enterClone(clone.dir, clone.name);
                 if (act === 1)
                     return cmdFinish([clone.name]);
                 if (act === 2)
@@ -719,17 +774,18 @@ async function cmdNew(argv) {
     let name = strFlag(flags, "name") ?? "";
     if (!name) {
         const def = tsName();
-        const prompt = `Kage name: ${basename(repoRoot)}--`;
+        const prompt = `Clone name: ${basename(repoRoot)}--`;
         name = (process.stdin.isTTY ? await ask(prompt, def) : "") || def;
     }
     const safe = slug(name);
     const cloneDir = join(dirname(repoRoot), `${basename(repoRoot)}--${safe}`);
     if (existsSync(cloneDir))
         die(`directory already exists: ${cloneDir}`);
-    // Resolve the agent to launch up front, so a typo fails before we copy anything.
-    const agentId = strFlag(flags, "agent") ?? process.env.KAGE_AGENT ?? "pi";
-    const agent = agentById(agentId);
-    if (!agent)
+    // Launch is opt-in: a CLI launches only if you named one (--agent / $KAGE_AGENT / `kage config agent`).
+    // Resolve it up front so a typo fails before we copy; with none set, kage just cd's you in (below).
+    const agentId = strFlag(flags, "agent") ?? process.env.KAGE_AGENT ?? readConfig().agent;
+    const agent = agentId ? agentById(agentId) : undefined;
+    if (agentId && !agent)
         die(`unknown agent: ${agentId} (supported: ${AGENTS.map((a) => a.id).join(", ")})`);
     const cp = await copyRepo(repoRoot, cloneDir);
     if (!cp.ok)
@@ -750,26 +806,22 @@ async function cmdNew(argv) {
     info(`🥷 ${paint.bold("Shadow clone ready")}: ${cloneDir}`);
     info(`   origin: ${repoRoot}   branch: ${paint.cyan(curBranch)}`);
     if (histN > 0)
-        info(paint.dim(`   origin's ${histN} session(s) are available via resume (pi: pick from the list)`));
-    info(paint.dim(`   when done: kage finish ${safe}`));
-    info("");
-    // Launch mode: --no-launch (just build), --open <cmd> (open + return), else spawn the CLI.
-    if (boolFlag(flags, "no-launch"))
-        return;
+        info(paint.dim(`   origin's ${histN} session(s) imported — resume them from inside the clone`));
+    // Optionally hand off to an agent, then settle the shell in the clone (always):
+    //   --open <cmd> → run it (e.g. an editor);  an agent named → spawn it (blocking);
+    //   else (--no-launch, or no agent set) → launch nothing.
     const openCmd = strFlag(flags, "open");
     if (openCmd || boolFlag(flags, "open")) {
         if (!openCmd)
             die("--open needs a command, e.g. --open code");
         launchOpen(openCmd, cloneDir);
-        info("");
-        info(`↩︎  opened ${cloneDir} with ${openCmd}. To finish: ${paint.bold(`kage finish ${safe}`)}`);
-        return;
     }
-    if (!agent.cli)
-        die(`agent ${agent.id} has no CLI to launch — use --open <cmd> or --no-launch`);
-    launchCli(agent.cli, cloneDir, agent.cli.freshArgs);
-    info("");
-    info(`↩︎  left the clone's ${agent.cli.bin}. To finish: ${paint.bold(`kage finish ${safe}`)}`);
+    else if (agent && !boolFlag(flags, "no-launch")) {
+        if (!agent.cli)
+            die(`agent ${agent.id} has no CLI to launch — use --open <cmd> or --no-launch`);
+        launchCli(agent.cli, cloneDir, agent.cli.freshArgs);
+    }
+    cdIntoClone(cloneDir, safe);
 }
 async function cmdFinish(argv) {
     const { positional, flags } = parseArgs(argv);
@@ -838,12 +890,7 @@ async function cmdFinish(argv) {
     let n = 0;
     for (const a of AGENTS)
         n += a.store.mergeBack(clone.dir, originRepo);
-    try {
-        process.chdir(originRepo);
-    }
-    catch {
-        /* ignore */
-    }
+    chdirToOrigin(originRepo);
     rmSync(clone.dir, { recursive: true, force: true });
     info(`💨 Clone dispelled: merged ${n} session(s) back, removed ${clone.dir}`);
     if (insideClone)
@@ -865,12 +912,7 @@ async function cmdRm(argv) {
         if (!(await confirm(`Discard clone ${clone.name} without merging its memory?`)))
             return info("aborted");
     }
-    try {
-        process.chdir(originRepo);
-    }
-    catch {
-        /* ignore */
-    }
+    chdirToOrigin(originRepo);
     for (const a of AGENTS)
         a.store.discard(clone.dir);
     rmSync(clone.dir, { recursive: true, force: true });
@@ -896,7 +938,7 @@ function cmdList(argv) {
         const s = cloneStatus(c.dir);
         const pr = boolFlag(flags, "pr") ? prInfo(c.dir, s.branch) : undefined;
         // header: status glyph · name · branch · age
-        const glyph = s.dirty ? paint.yellow("●") : isSafeToClean(s) ? paint.green("✓") : paint.cyan("·");
+        const glyph = statusTag(s);
         const age = paint.dim(`created ${ago(c.marker.createdAt)}`);
         info(`  ${glyph} ${paint.bold(c.name)}  ${paint.cyan(s.branch)}  ${age}`);
         // detail: working-tree state · sync · PR · safe-to-clean
@@ -973,6 +1015,41 @@ function cmdPull(argv) {
     }
     info(`📤 Pulled ${done}/${positional.length} path(s) from the clone back to the origin (${originRepo})`);
 }
+/** get/set kage's small persisted config (~/.config/kage/config.json). Keys are validated so a
+ *  typo can't silently become a "default". `kage config` (no args) prints the file path + every key. */
+function cmdConfig(argv) {
+    const { positional, flags } = parseArgs(argv);
+    const cfg = readConfig();
+    const key = positional[0] ?? (typeof flags.unset === "string" ? flags.unset : undefined);
+    const value = positional[1];
+    if (!key) {
+        info(paint.dim(`# ${configPath()}`));
+        for (const k of CONFIG_KEYS)
+            info(`${k} = ${cfg[k] ?? paint.dim("(unset)")}`);
+        return;
+    }
+    if (!CONFIG_KEYS.includes(key)) {
+        die(`unknown config key: ${key} (known: ${CONFIG_KEYS.join(", ")})`);
+    }
+    const k = key;
+    if (boolFlag(flags, "unset")) {
+        delete cfg[k];
+        writeConfig(cfg);
+        info(`unset ${k}`);
+        return;
+    }
+    if (value === undefined) {
+        // a bare read goes to stdout so `X=$(kage config <key>)` works; other output stays on stderr
+        process.stdout.write(`${cfg[k] ?? ""}\n`);
+        return;
+    }
+    if (k === "agent" && !agentById(value)) {
+        die(`unknown agent: ${value} (supported: ${AGENTS.map((a) => a.id).join(", ")})`);
+    }
+    cfg[k] = value;
+    writeConfig(cfg);
+    info(`${k} = ${value}`);
+}
 const SHELL_INIT = `# kage shell integration — add to ~/.zshrc or ~/.bashrc:  eval "$(kage shell-init)"
 kage() {
   local f; f="$(mktemp "\${TMPDIR:-/tmp}/kage-cd.XXXXXX")"
@@ -983,18 +1060,20 @@ kage() {
 }
 if [ -n "$ZSH_VERSION" ]; then
   _kage() {
-    if (( CURRENT == 2 )); then compadd new status finish rm pull; return; fi
+    if (( CURRENT == 2 )); then compadd new status finish rm pull config; return; fi
     case "\${words[2]}" in
       finish|rm) compadd $(command kage __clones 2>/dev/null);;
+      config) compadd agent;;
     esac
   }
   compdef _kage kage
 elif [ -n "$BASH_VERSION" ]; then
   _kage() {
     local cur="\${COMP_WORDS[COMP_CWORD]}"
-    if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=( $(compgen -W "new status finish rm pull" -- "$cur") ); return; fi
+    if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=( $(compgen -W "new status finish rm pull config" -- "$cur") ); return; fi
     case "\${COMP_WORDS[1]}" in
       finish|rm) COMPREPLY=( $(compgen -W "$(command kage __clones 2>/dev/null)" -- "$cur") );;
+      config) COMPREPLY=( $(compgen -W "agent" -- "$cur") );;
     esac
   }
   complete -F _kage kage
@@ -1009,8 +1088,8 @@ function cmdClones() {
 const HELP = `kage 🥷 — Shadow Clone Jutsu for your git repo
 
 Usage:
-  kage [path] [--name <x>] [--agent <id>]              clone repo + launch a fresh agent (default: pi)
-                                                       --open <cmd> | --no-launch: open it yourself instead
+  kage [path] [--name <x>] [--agent <id>]              clone the repo and cd into it (launch an agent only if one is set)
+                                                       --open <cmd> opens it elsewhere; --no-launch skips the agent
                                                        (no args inside a repo with clones: interactive menu)
   kage status [--pr]                                   dashboard of clones (--pr adds PR status via gh)
   kage finish [name] [--force] [--push] [--pr]         preserve work -> merge memory back -> delete clone
@@ -1018,7 +1097,8 @@ Usage:
                                                         kept in the origin as a local 'kage/<name>-<sha>' branch)
   kage rm [name] [--force]                             discard a clone without merging
   kage pull <path...>                                  (inside a clone) copy files back to the origin
-  kage shell-init                                      shell wrapper (cd-back) + tab completion
+  kage config [<key> [value]] [--unset]                get/set persisted defaults (e.g. the launch agent)
+  kage shell-init                                      shell wrapper (cd into clones / back) + tab completion
   kage --help | --version                              show this help / print the version
 
 With no args inside a repo that already has clones, kage opens an interactive menu
@@ -1027,15 +1107,16 @@ With no args inside a repo that already has clones, kage opens an interactive me
 Options:
   --name <x>    name the clone folder /<repo>--<x> (default: kage-<timestamp>); skips the name prompt
                 (sanitized to a git-ref-safe slug, since the name is also used as a branch name)
-  --agent <id>  which agent CLI to launch (default: pi, or $KAGE_AGENT); memory still syncs for all agents
-  --open <cmd>  after cloning, run '<cmd> <clone>' (e.g. --open code) and return, instead of spawning a CLI
-  --no-launch   just create the clone (and import memory), print its path; you open it yourself
+  --agent <id>  launch this agent CLI in the clone (one-off). with none set (--agent > $KAGE_AGENT >
+                'kage config agent') kage just cd's you into the clone. memory syncs for every agent
+  --open <cmd>  after cloning, run '<cmd> <clone>' (e.g. --open code), then cd into the clone
+  --no-launch   don't launch an agent even if one is configured — just create the clone and cd in
   --pr          (finish) push the branch and open a GitHub PR via gh, then finish
   --push        (finish) push the branch before finishing (implied by --pr)
   --force       skip the safety checks: uncommitted/unpushed guard (finish) or local-only guard (rm)
 
 Examples:
-  kage                          # clone the current repo, pick a name, open a fresh pi to work in
+  kage                          # clone the current repo, pick a name, and cd into the clone
   kage --name fix-login         # same, but name the clone ../<repo>--fix-login (no prompt)
   kage ~/code/other-repo        # clone a different repo instead of the current dir
 
@@ -1049,9 +1130,10 @@ Examples:
   kage rm experiment            # throw a clone away without merging its memory
 
   kage pull .env                # inside a clone: copy a gitignored file back to the origin
+  kage config agent claude      # launch claude on create (instead of just cd-ing into the clone)
 
 Env (each agent's own native var — kage just honors it, so kage and the agent always agree):
-  KAGE_AGENT            default agent to launch when --agent is omitted (default: pi)
+  KAGE_AGENT            agent to launch on create when --agent is omitted (none set = just cd into the clone)
   PI_CODING_AGENT_DIR   pi's agent dir; sessions read from <it>/sessions (default: ~/.pi/agent)
   CLAUDE_CONFIG_DIR     Claude Code's config dir; sessions read from <it>/projects (default: ~/.claude)
   CODEX_HOME            Codex's home dir; sessions read from <it>/sessions (default: ~/.codex)`;
@@ -1069,6 +1151,8 @@ async function main() {
             return cmdRm(rest);
         case "pull":
             return cmdPull(rest);
+        case "config":
+            return cmdConfig(rest);
         case "shell-init": {
             process.stdout.write(`${SHELL_INIT}\n`);
             // When a human runs this directly (stdout is a TTY, not captured by `$(...)`),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-kage",
-  "version": "0.4.0",
-  "description": "🥷 Shadow Clone Jutsu for your git repo: copy it into an isolated folder, work in parallel with pi, then merge the session memory back",
+  "version": "0.5.0",
+  "description": "🥷 Shadow Clone Jutsu for your git repo: copy it into an isolated sibling folder, run your coding agent (pi, Claude Code, Codex) in parallel, then merge the session memory back",
   "keywords": [
     "pi",
     "coding-agent",