pi-kage 0.3.8 → 0.5.0

package/README.md

@@ -15,14 +15,20 @@ 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
-`~/.pi`. kage never copies a working tree back onto the origin — that's the whole point.
+its own session store (`~/.pi`, `~/.claude`, or `~/.codex`). kage never copies a working tree back onto
+the origin — that's the whole point.
 
 ## Why a full copy, not `git worktree`?
 
@@ -46,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:
 
@@ -56,31 +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]` | origin repo | Copy the repo to `../<repo>--<name>` (default `kage-<ts>`), copy in the origin's 5 most recent pi sessions (resumable, never replayed), and launch a **fresh** pi. `--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 list` is an alias.) |
-| `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 [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 | 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.
 
-### Shell integration (optional)
+## 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.
+
+**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 (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
 
@@ -91,10 +127,11 @@ completion for subcommands and clone names.
   Without a remote: `finish` fetches the clone's branch into the origin's git as a local
   `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 `~/.pi`, never replayed.** On create, the origin's 5 most recent sessions are
-  copied in — pi'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.
+- **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 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.
 
@@ -103,7 +140,9 @@ completion for subcommands and clone names.
 - The copy snapshots the origin's **current** state, including uncommitted changes.
 - **Submodules**: a submodule's `.git` is an absolute path and breaks on copy — run
   `git submodule update --init` in the clone.
-- Session storage defaults to `~/.pi/agent/sessions`; override with `KAGE_SESSIONS_DIR`.
+- kage reads each agent's sessions from where that agent itself stores them, honoring the agent's own
+  config var — `PI_CODING_AGENT_DIR` (pi), `CLAUDE_CONFIG_DIR` (Claude Code), `CODEX_HOME` (Codex) — so
+  kage and the agent always agree on the location.
 
 ## Development
 

package/README.zh-CN.md

@@ -14,14 +14,19 @@
 
 ```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 回原仓库
 ```
 
-代码通过 git 回流（一个 PR，或者 fetch 分支）；agent 的 session 记忆通过 `~/.pi` 回流。kage 从不把工作区
-复制回原仓库 —— 这正是它存在的意义。
+启动 agent 是可选的：纯跑 `kage` 只是建好分身并把你 cd 进去 —— `--agent`（或 `kage config agent`、或
+`$KAGE_AGENT`）才是告诉 kage 替你启动一个的开关。
+
+代码通过 git 回流（一个 PR，或者 fetch 分支）；agent 的 session 记忆通过它自己的 session 存储（`~/.pi`、
+`~/.claude` 或 `~/.codex`）回流。kage 从不把工作区复制回原仓库 —— 这正是它存在的意义。
 
 ## 为什么用完整副本，而不是 `git worktree`？
 
@@ -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,29 +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]` | 原仓库 | 把仓库复制到 `../<repo>--<name>`（默认 `kage-<ts>`），拷入原仓库最近 5 个 pi session（可 resume，绝不重放），并启动一个**全新**的 pi。`--name` 只命名文件夹 —— kage 从不建分支。无参数 + 已有分身 → 进入交互菜单。 |
-| `kage status [--pr]` | 原仓库 | 仪表盘：分支、是否有改动、ahead/behind、是否「可安全清理」。`--pr` 通过 `gh` 附带 PR 状态。（`kage list` 是别名。） |
-| `kage finish [name] [--force] [--push] [--pr]` | 原仓库 / 分身内 | 若分身有未提交或未 push 的改动则拒绝，把它**新产生**的 session 合并回来，再删除它。`--push` 先 push 分支；`--pr` push 并通过 `gh` 开 PR；`--force` 跳过检查。 |
+| `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]` | 原仓库 / 分身内 | 先保留分身的 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` 也会弹出同样的选择器。
 
-### Shell 集成（可选）
+## 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 拉不起来的 GUI/IDE agent？** 用 `--open <cmd>` 建好分身后自己打开它（比如 `kage --open code`
+会执行 `code <clone>`），或用 `--no-launch` 只建分身并打印路径。无论你怎么打开分身，只要是 kage 管理其
+store 的 agent，记忆照样回流。
+
+## 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 补全。
 
 ## 工作原理
 
@@ -84,9 +117,10 @@ eval "$(kage shell-init)"   # 加到 ~/.zshrc 或 ~/.bashrc
 - **代码只经由 git 回流，绝不经过工作区。** 有 remote 时：push 分支、合并 PR。没有 remote 时：`finish` 会把
   分身的分支 fetch 进原仓库的 git，存成本地分支 `kage/<name>-<sha>`（原仓库工作区不动 —— 你想合并时再
   `git merge`）。由于 fetch 无法保留未提交的改动，`finish` 拒绝删除有改动的分身，除非加 `--force`。
-- **记忆只经由 `~/.pi` 回流，绝不重放。** 创建时拷入原仓库最近 5 个 session —— pi 的 resume 选择器能看到它们，
-  但分身本身打开的是**全新** session。`finish` 时，分身自己产生的 session 整份拷回；你 resume 过的拷入 session
-  会作为一个独立的新 session 回来，原仓库的原始 session 绝不被改动。
+- **记忆经由该 agent 自己的 session 存储回流，绝不重放。** 创建时拷入原仓库最近 5 个该 agent 的 session —— 该
+  agent 的 resume 选择器在你启动它时能看到它们，但你从一个**全新** session 开始。`finish` 时，分身自己产生的 session 整份
+  拷回；你 resume 过的拷入 session 会作为一个独立的新 session 回来，原仓库的原始 session 绝不被改动。（Codex 是
+  例外 —— 仅 git 回流；见 [Agents](#agents)。）
 - **对 kage 而言原仓库是只读的。** 它只往外复制、只写 session 记忆 —— 即使原仓库里另有一个 session 正活跃，
   它也绝不碰原仓库的工作区。
 
@@ -95,7 +129,9 @@ eval "$(kage shell-init)"   # 加到 ~/.zshrc 或 ~/.bashrc
 - 副本是原仓库**当前**状态的快照，包含未提交的改动。
 - **Submodule**：submodule 的 `.git` 是绝对路径，复制后会失效 —— 在分身里跑一次
   `git submodule update --init`。
-- Session 存储默认在 `~/.pi/agent/sessions`，可用 `KAGE_SESSIONS_DIR` 覆盖。
+- kage 从每个 agent **自己**存 session 的地方去读，尊重该 agent 自己的配置变量 ——
+  `PI_CODING_AGENT_DIR`（pi）、`CLAUDE_CONFIG_DIR`（Claude Code）、`CODEX_HOME`（Codex）—— 这样
+  kage 和 agent 永远指向同一个位置。
 
 ## 开发
 

package/bin/kage.mjs

@@ -2,35 +2,32 @@
 /**
  * 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]                           clone repo + launch a fresh pi (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";
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import readline from "node:readline";
-const VERSION = "0.3.8"; // 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 SESSIONS = process.env.KAGE_SESSIONS_DIR || join(homedir(), ".pi", "agent", "sessions");
 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. */
 const boolFlag = (flags, name) => Boolean(flags[name]);
@@ -64,16 +61,16 @@ function sh(cmd, args, opts = {}) {
     return { ok: r.status === 0, out: (r.stdout || "").trim(), err: (r.stderr || "").trim() };
 }
 const git = (cwd, args) => sh("git", args, { cwd });
-/** Absolute path -> pi's session dir name: /a/b -> --a-b-- */
-const encodeCwd = (abs) => `--${abs.replace(/^\//, "").replace(/\//g, "-")}--`;
-const sessionDirFor = (repoAbs) => join(SESSIONS, encodeCwd(repoAbs));
 function repoTopLevel(cwd) {
     const r = git(cwd, ["rev-parse", "--show-toplevel"]);
     return r.ok ? r.out : undefined;
 }
-/** Validate parsed JSON is a kage marker (only originRepo is required; name/createdAt are best-effort). */
+/** Validate parsed JSON has the shape kage writes (all three fields are strings). */
 function isMarker(v) {
-    return typeof v === "object" && v !== null && typeof v.originRepo === "string";
+    if (typeof v !== "object" || v === null)
+        return false;
+    const m = v;
+    return typeof m.originRepo === "string" && typeof m.name === "string" && typeof m.createdAt === "string";
 }
 function readMarker(dir) {
     const p = join(dir, MARKER);
@@ -87,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";
@@ -185,7 +210,7 @@ function listClones(originRepo) {
         const dir = join(parent, name);
         const m = readMarker(dir);
         if (m && m.originRepo === originRepo)
-            out.push({ dir, name: m.name || basename(dir), marker: m });
+            out.push({ dir, name: m.name, marker: m });
     }
     return out;
 }
@@ -247,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)
@@ -322,14 +355,14 @@ async function pickClone(action, name) {
     const here = repoTopLevel(process.cwd());
     const hm = here ? readMarker(here) : undefined;
     if (here && hm && !name)
-        return { originRepo: hm.originRepo, clone: { dir: here, name: hm.name || basename(here), marker: hm } };
+        return { originRepo: hm.originRepo, clone: { dir: here, name: hm.name, marker: hm } };
     // If `name` resolves to a clone directory, use its marker directly — works from anywhere,
     // even outside a repo (e.g. `kage rm ../app--fix` from the parent dir).
     if (name) {
         const asPath = resolve(name);
         const pm = readMarker(asPath);
         if (pm)
-            return { originRepo: pm.originRepo, clone: { dir: asPath, name: pm.name || basename(asPath), marker: pm } };
+            return { originRepo: pm.originRepo, clone: { dir: asPath, name: pm.name, marker: pm } };
     }
     const originRepo = hm ? hm.originRepo : here;
     if (!originRepo)
@@ -346,159 +379,355 @@ 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;
     return { originRepo, clone: chosen };
 }
-// ── copy the origin's session history into the clone ─────────────────────────
-/**
- * Copies the origin's most recent session files (up to RECENT_SESSIONS, by mtime) into the
- * clone's session dir, so `pi` resume inside the clone surfaces them (you decide whether to
- * resume any of it). The clone itself opens a fresh session — kage never replays turns or
- * fabricates a "resumed" conversation. On merge-back an unchanged copy adds nothing; if you
- * resumed one and added turns, it comes back as a separate session (see mergeBack).
- */
-function copyOriginHistory(originRepo, cloneDir) {
-    const srcDir = sessionDirFor(originRepo);
-    if (!existsSync(srcDir))
-        return 0;
-    const destDir = sessionDirFor(cloneDir);
-    mkdirSync(destDir, { recursive: true });
-    const recent = readdirSync(srcDir)
-        .filter((f) => f.endsWith(".jsonl"))
-        .map((f) => ({ f, m: statSync(join(srcDir, f)).mtimeMs }))
-        .sort((a, b) => b.m - a.m)
-        .slice(0, RECENT_SESSIONS);
-    let n = 0;
-    for (const { f } of recent) {
-        const lines = readFileSync(join(srcDir, f), "utf8").split("\n");
-        try {
-            const header = JSON.parse(lines[0] ?? "");
-            header.cwd = cloneDir;
-            lines[0] = JSON.stringify(header);
-        }
-        catch {
-            /* leave malformed header as-is */
-        }
-        writeFileSync(join(destDir, f), lines.join("\n"));
-        n++;
-    }
-    return n;
-}
-// ── merge the clone's new sessions back into the origin ──────────────────────
 /**
- * Copies the clone's sessions into the origin's session dir:
- *   - a session the clone created (filename not in the origin) -> copied back whole.
- *   - a copied-in origin session left unchanged -> skipped (nothing new).
- *   - a copied-in origin session you resumed and added turns to -> written back as a NEW,
- *     self-contained session file, so the origin's original session (and the active leaf pi
- *     resumes) is never mutated. Costs a duplicated prefix; avoids hijacking the origin's leaf.
+ * The cwd→directory algorithm, shared by pi and (later) Claude Code:
+ *   - importHistory: copy the origin dir's most-recent sessions into the clone dir (cwd rewritten).
+ *   - mergeBack: a session the clone created comes back whole; a copied-in origin session left
+ *     unchanged is skipped; a copied-in session the clone resumed and extended comes back as a
+ *     NEW self-contained file, so the origin's original (and the leaf it resumes) is untouched.
  */
-function mergeBack(cloneDir, originRepo) {
-    const srcDir = sessionDirFor(cloneDir);
-    if (!existsSync(srcDir))
-        return 0;
-    const destDir = sessionDirFor(originRepo);
-    mkdirSync(destDir, { recursive: true });
-    let n = 0;
-    for (const f of readdirSync(srcDir)) {
-        if (!f.endsWith(".jsonl"))
-            continue;
-        const src = readFileSync(join(srcDir, f), "utf8")
-            .split("\n")
-            .filter((l) => l.trim());
-        if (src.length === 0)
-            continue;
-        const dest = join(destDir, f);
-        if (!existsSync(dest)) {
-            let header;
+function dirStore(cfg) {
+    const dirFor = (cwd) => join(cfg.baseDir(), cfg.encodeCwd(cwd));
+    return {
+        id: cfg.id,
+        importHistory(originRepo, cloneDir) {
+            const srcDir = dirFor(originRepo);
+            if (!existsSync(srcDir))
+                return 0;
+            const destDir = dirFor(cloneDir);
+            mkdirSync(destDir, { recursive: true });
+            const recent = readdirSync(srcDir)
+                .filter((f) => f.endsWith(".jsonl"))
+                .map((f) => ({ f, m: statSync(join(srcDir, f)).mtimeMs }))
+                .sort((a, b) => b.m - a.m)
+                .slice(0, RECENT_SESSIONS);
+            let n = 0;
+            for (const { f } of recent) {
+                const lines = readFileSync(join(srcDir, f), "utf8").split("\n");
+                writeFileSync(join(destDir, f), cfg.setCwd(lines, cloneDir).join("\n"));
+                n++;
+            }
+            return n;
+        },
+        mergeBack(cloneDir, originRepo) {
+            const srcDir = dirFor(cloneDir);
+            if (!existsSync(srcDir))
+                return 0;
+            const destDir = dirFor(originRepo);
+            mkdirSync(destDir, { recursive: true });
+            let n = 0;
+            for (const f of readdirSync(srcDir)) {
+                if (!f.endsWith(".jsonl"))
+                    continue;
+                const src = readFileSync(join(srcDir, f), "utf8")
+                    .split("\n")
+                    .filter((l) => l.trim());
+                if (src.length === 0)
+                    continue;
+                const dest = join(destDir, f);
+                // A session the clone created (not present in the origin) -> copy it back whole.
+                if (!existsSync(dest)) {
+                    writeFileSync(dest, `${cfg.setCwd(src, originRepo).join("\n")}\n`);
+                    n++;
+                    continue;
+                }
+                // A copied-in origin session: write back only if the clone added records, and then as
+                // a NEW, self-contained file so the origin's original (and the leaf it resumes) is never
+                // mutated. An unchanged copy adds nothing.
+                const have = new Set();
+                for (const l of readFileSync(dest, "utf8").split("\n")) {
+                    if (!l.trim())
+                        continue;
+                    try {
+                        have.add(cfg.recordId(l));
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+                const hasNew = src.slice(1).some((l) => {
+                    try {
+                        return !have.has(cfg.recordId(l));
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                if (!hasNew)
+                    continue;
+                const fresh = cfg.reidentify(src, originRepo);
+                writeFileSync(join(destDir, fresh.filename), `${fresh.lines.join("\n")}\n`);
+                n++;
+            }
             try {
-                header = JSON.parse(src[0] ?? "");
+                rmSync(srcDir, { recursive: true, force: true });
             }
-            catch {
-                continue;
+            catch (e) {
+                info(paint.dim(`   (couldn't clear the clone's ${cfg.id} sessions at ${srcDir}: ${e.message})`));
             }
-            header.cwd = originRepo;
-            writeFileSync(dest, `${[JSON.stringify(header), ...src.slice(1)].join("\n")}\n`);
-            n++;
-            continue;
-        }
-        // A copied-in origin session. If the clone added records (e.g. you resumed it there),
-        // write the clone's full session back as a NEW, self-contained file — leaving the origin's
-        // original file (and the leaf pi resumes) untouched. Unchanged copies add nothing.
-        const have = new Set();
-        for (const l of readFileSync(dest, "utf8").split("\n")) {
-            if (!l.trim())
-                continue;
+            return n;
+        },
+        discard(cloneDir) {
+            const d = dirFor(cloneDir);
             try {
-                have.add(JSON.parse(l).id);
+                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})`));
             }
-        }
-        const hasNew = src.slice(1).some((l) => {
+        },
+        hasActivity(cwd) {
+            const d = dirFor(cwd);
             try {
-                return !have.has(JSON.parse(l).id);
+                return existsSync(d) && readdirSync(d).some((f) => f.endsWith(".jsonl"));
             }
             catch {
                 return false;
             }
-        });
-        if (!hasNew)
-            continue;
-        let header;
+        },
+    };
+}
+/** pi: one session per .jsonl, cwd in a first-line header, per-line `id` for dedup. */
+const piStore = dirStore({
+    id: "pi",
+    baseDir: () => join(process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent"), "sessions"),
+    encodeCwd: (abs) => `--${abs.replace(/^\//, "").replace(/\//g, "-")}--`,
+    setCwd(lines, cwd) {
+        const out = [...lines];
         try {
-            header = JSON.parse(src[0] ?? "");
+            const header = JSON.parse(out[0] ?? "");
+            header.cwd = cwd;
+            out[0] = JSON.stringify(header);
         }
         catch {
-            continue;
+            /* leave a malformed header as-is rather than drop the session */
+        }
+        return out;
+    },
+    recordId: (line) => JSON.parse(line).id,
+    reidentify(lines, cwd) {
+        let header = {};
+        try {
+            header = JSON.parse(lines[0] ?? "");
+        }
+        catch {
+            /* synthesize a minimal header below */
         }
         const id = randomUUID();
-        const fname = `${new Date().toISOString().replace(/[:.]/g, "-")}_${id}.jsonl`;
-        writeFileSync(join(destDir, fname), `${[JSON.stringify({ ...header, id, cwd: originRepo }), ...src.slice(1)].join("\n")}\n`);
-        n++;
-    }
+        const filename = `${new Date().toISOString().replace(/[:.]/g, "-")}_${id}.jsonl`;
+        return { filename, lines: [JSON.stringify({ ...header, id, cwd }), ...lines.slice(1)] };
+    },
+});
+/** Apply a JSON transform to every parseable line, leaving blank/malformed lines untouched. */
+function mapJsonLines(lines, fn) {
+    return lines.map((l) => {
+        if (!l.trim())
+            return l;
+        try {
+            const rec = JSON.parse(l);
+            fn(rec);
+            return JSON.stringify(rec);
+        }
+        catch {
+            return l;
+        }
+    });
+}
+/** Claude Code: one session per <sessionId>.jsonl, with cwd + sessionId repeated on every line. */
+const claudeStore = dirStore({
+    id: "claude",
+    baseDir: () => join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"),
+    encodeCwd: (abs) => abs.replace(/[^A-Za-z0-9]/g, "-"),
+    setCwd: (lines, cwd) => mapJsonLines(lines, (r) => {
+        if ("cwd" in r)
+            r.cwd = cwd;
+    }),
+    recordId: (line) => JSON.parse(line).uuid,
+    reidentify(lines, cwd) {
+        const id = randomUUID();
+        const out = mapJsonLines(lines, (r) => {
+            if ("sessionId" in r)
+                r.sessionId = id;
+            if ("cwd" in r)
+                r.cwd = cwd;
+        });
+        return { filename: `${id}.jsonl`, lines: out };
+    },
+});
+const codexSessionsDir = () => join(process.env.CODEX_HOME || join(homedir(), ".codex"), "sessions");
+/**
+ * Read just the first line of a (possibly large) file, without loading the whole thing.
+ * Accumulates raw bytes and decodes once at the end — decoding each read as UTF-8 would corrupt
+ * any multibyte char split across an 8 KiB read boundary (real Codex session_meta lines are tens
+ * of KiB of mixed-script text).
+ */
+function readFirstLine(file) {
+    const fd = openSync(file, "r");
     try {
-        rmSync(srcDir, { recursive: true, force: true });
+        const buf = Buffer.alloc(8192);
+        const chunks = [];
+        for (;;) {
+            const bytes = readSync(fd, buf, 0, buf.length, null);
+            if (bytes <= 0)
+                break;
+            const nl = buf.subarray(0, bytes).indexOf(0x0a); // newline byte
+            if (nl >= 0) {
+                chunks.push(Buffer.from(buf.subarray(0, nl)));
+                break;
+            }
+            chunks.push(Buffer.from(buf.subarray(0, bytes)));
+        }
+        return Buffer.concat(chunks).toString("utf8");
     }
-    catch {
-        /* ignore */
+    finally {
+        closeSync(fd);
     }
-    return n;
+}
+/** Every rollout-*.jsonl under the Codex sessions tree, paired with its session_meta cwd. */
+function codexRollouts() {
+    const base = codexSessionsDir();
+    if (!existsSync(base))
+        return [];
+    const out = [];
+    const walk = (dir) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const p = join(dir, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")) {
+                let cwd;
+                try {
+                    cwd = JSON.parse(readFirstLine(p)).payload?.cwd;
+                }
+                catch {
+                    /* not a session_meta we understand */
+                }
+                out.push({ file: p, cwd });
+            }
+        }
+    };
+    walk(base);
+    return out;
 }
 /**
- * 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.
+ * Codex keeps every session in one global tree shared by all cwds, and (since 0.13x) keys its
+ * cwd-filtered resume picker off a *versioned internal sqlite index* (e.g. state_5.sqlite's
+ * `threads.cwd`), not the rollout. kage can't re-home a clone's sessions to the origin without
+ * rewriting that sqlite — fragile (the schema/db version moves between Codex releases) and a
+ * runtime dependency kage avoids. So kage does NOT manage Codex memory: `--agent codex` gives the
+ * isolated clone + git flow-back, and Codex history stays globally available via
+ * `codex resume --all`. import/mergeBack/discard are intentional no-ops; hasActivity (a rollout
+ * scan, never the sqlite) only powers the re-enter menu while a clone still exists.
  */
-function leaveClone(originRepo) {
+const codexStore = {
+    id: "codex",
+    importHistory: () => 0,
+    mergeBack: () => 0,
+    discard: () => { },
+    hasActivity(cwd) {
+        return codexRollouts().some((r) => r.cwd === cwd);
+    },
+};
+// 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 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"] } },
+    { id: "codex", store: codexStore, cli: { bin: "codex", freshArgs: [], resumeArgs: ["resume", "--last"] } },
+];
+const agentById = (id) => AGENTS.find((a) => a.id === id);
+function launchCli(cli, cwd, args) {
+    const r = spawnSync(cli.bin, args, { cwd, stdio: "inherit" });
+    if (r.error) {
+        const err = r.error;
+        if (err.code === "ENOENT")
+            die(`${cli.bin} not found (make sure it is installed and on your PATH)`);
+        die(`failed to launch ${cli.bin}: ${err.message}`);
+    }
 }
-function launchPi(cwd, args) {
-    const r = spawnSync("pi", args, { cwd, stdio: "inherit" });
+/** Open the clone with an external command (e.g. `code <clone>`) and return immediately. */
+function launchOpen(cmd, cwd) {
+    const parts = cmd.split(/\s+/).filter(Boolean);
+    const bin = parts[0];
+    if (!bin)
+        die("--open needs a command, e.g. --open code");
+    const r = spawnSync(bin, [...parts.slice(1), cwd], { stdio: "inherit" });
     if (r.error) {
         const err = r.error;
         if (err.code === "ENOENT")
-            die("pi not found (make sure it is installed and on your PATH)");
-        die(`failed to launch pi: ${err.message}`);
+            die(`${bin} not found (make sure it is installed and on your PATH)`);
+        die(`failed to run --open ${cmd}: ${err.message}`);
     }
 }
+/** 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));
+    let chosen = active[0]; // undefined when nothing has activity here
+    if (active.length > 1) {
+        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) {
     const { positional, flags } = parseArgs(argv);
@@ -508,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 pi)", "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 launchPi(clone.dir, ["-c"]);
+                    return enterClone(clone.dir, clone.name);
                 if (act === 1)
                     return cmdFinish([clone.name]);
                 if (act === 2)
@@ -547,18 +774,27 @@ 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}`);
+    // 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)
         die(`copy failed: ${cp.err}`);
     // kage does NOT create a branch — the clone stays on the origin's current branch.
-    const histN = copyOriginHistory(repoRoot, cloneDir);
+    // Set-based memory: each agent's store imports its own origin history (no-op when empty).
+    let histN = 0;
+    for (const a of AGENTS)
+        histN += a.store.importHistory(repoRoot, cloneDir);
     const marker = {
         originRepo: repoRoot,
         name: safe,
@@ -570,12 +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("");
-    launchPi(cloneDir, []);
-    info("");
-    info(`↩︎  left the clone's pi. To finish: ${paint.bold(`kage finish ${safe}`)}`);
+        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);
+    }
+    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);
@@ -641,13 +887,10 @@ async function cmdFinish(argv) {
             die(`failed to preserve the clone's branch into the origin: ${r.err}`);
         info(`🌿 preserved the clone's commits in the origin as ${paint.cyan(target)}  (merge with: git merge ${target})`);
     }
-    const n = mergeBack(clone.dir, originRepo);
-    try {
-        process.chdir(originRepo);
-    }
-    catch {
-        /* ignore */
-    }
+    let n = 0;
+    for (const a of AGENTS)
+        n += a.store.mergeBack(clone.dir, originRepo);
+    chdirToOrigin(originRepo);
     rmSync(clone.dir, { recursive: true, force: true });
     info(`💨 Clone dispelled: merged ${n} session(s) back, removed ${clone.dir}`);
     if (insideClone)
@@ -669,18 +912,9 @@ async function cmdRm(argv) {
         if (!(await confirm(`Discard clone ${clone.name} without merging its memory?`)))
             return info("aborted");
     }
-    try {
-        process.chdir(originRepo);
-    }
-    catch {
-        /* ignore */
-    }
-    try {
-        rmSync(sessionDirFor(clone.dir), { recursive: true, force: true });
-    }
-    catch {
-        /* ignore */
-    }
+    chdirToOrigin(originRepo);
+    for (const a of AGENTS)
+        a.store.discard(clone.dir);
     rmSync(clone.dir, { recursive: true, force: true });
     info(`🗑  Removed clone ${clone.name} (${clone.dir})`);
     if (insideClone)
@@ -704,8 +938,8 @@ 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 age = c.marker?.createdAt ? paint.dim(`created ${ago(c.marker.createdAt)}`) : "";
+        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
         const parts = [];
@@ -781,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")"
@@ -791,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
@@ -817,7 +1088,8 @@ function cmdClones() {
 const HELP = `kage 🥷 — Shadow Clone Jutsu for your git repo
 
 Usage:
-  kage [path] [--name <x>]                             clone repo + launch a fresh pi
+  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
@@ -825,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
@@ -834,12 +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>  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
 
@@ -853,9 +1130,13 @@ 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:
-  KAGE_SESSIONS_DIR   pi session storage (default: ~/.pi/agent/sessions)`;
+Env (each agent's own native var — kage just honors it, so kage and the agent always agree):
+  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)`;
 async function main() {
     const [sub, ...rest] = process.argv.slice(2);
     switch (sub) {
@@ -863,7 +1144,6 @@ async function main() {
         case "new":
             return cmdNew(sub === "new" ? rest : process.argv.slice(2));
         case "status":
-        case "list": // alias
             return cmdList(rest);
         case "finish":
             return cmdFinish(rest);
@@ -871,8 +1151,9 @@ async function main() {
             return cmdRm(rest);
         case "pull":
             return cmdPull(rest);
-        case "shell-init":
-        case "completion": {
+        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 `$(...)`),
             // the script just scrolled past unused — show how to actually activate it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-kage",
-  "version": "0.3.8",
-  "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",