pi-kage 0.3.7 → 0.4.0

package/README.md

@@ -4,115 +4,86 @@
 [![npm](https://img.shields.io/npm/v/pi-kage)](https://www.npmjs.com/package/pi-kage)
 [![license](https://img.shields.io/npm/l/pi-kage)](./LICENSE)
 
-> **影分身の術** — cast the **Shadow Clone Jutsu** on your git repo.
+> 影分身の術 — Shadow Clone Jutsu for your git repo. · [中文](./README.zh-CN.md)
 
 <p align="center"><img src="./assets/demo.svg" alt="kage demo" width="100%"></p>
 
-`kage` runs multiple AI coding-agent sessions against one repo in parallel. The problem it solves:
-point two agents at the same checkout and they fight over one working tree — editing the same files,
-colliding on branches, tripping over each other's uncommitted changes.
-
-Instead of a shared [`git worktree`](https://git-scm.com/docs/git-worktree), kage gives each session
-its own **full copy** of the repo in a sibling folder — its own working tree, its own `.git`. 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, so concurrent sessions can't collide.
-And like a real Naruto shadow clone, the clone carries the agent's memory out and returns it on
-dispel (see [How it works](#how-it-works)).
+Run several AI coding-agent sessions on one repo at the same time. Point two agents at the same
+checkout and they fight over one working tree — same files, same branches, each other's uncommitted
+changes. kage gives each session its **own full copy** of the repo in a sibling folder, so they
+can't collide.
 
 ```bash
 npm install -g pi-kage
 cd my-app
-kage                 # 🥷 clone -> ../my-app--kage-<ts>, open a fresh pi (origin history resumable)
-#   ...work in the clone: commit, push, open a PR, quit pi...
-kage finish          # 💨 merge the clone's new sessions back, delete the clone
+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
 ```
 
----
-
-## Why a full copy instead of `git worktree`?
+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.
 
-A worktree is the obvious way to get a second working directory, but every worktree shares the
-repo's single `.git`. For parallel agents that shared `.git` is the problem:
+## Why a full copy, not `git worktree`?
 
-- you can't check out the same branch in two worktrees;
-- stash, refs, config, and the index are shared;
-- a worktree is a clean checkout — no `node_modules`, `.env`, `.venv`, or build cache — so each one
-  needs a full setup pass before the agent can build or run anything.
+A [`git worktree`](https://git-scm.com/docs/git-worktree) gives you a second working directory, but
+every worktree shares one `.git` — so two agents can't check out the same branch, and stash/refs/index
+are shared. A worktree is also a clean checkout: no `node_modules`, `.env`, build cache, so each one
+needs a setup pass first.
 
-A full copy has none of those constraints: independent `.git`, independent branches, and every
-untracked or gitignored file is already in place. The price is disk and copy time — which on macOS
-APFS kage avoids with a `cp -c` clonefile (copy-on-write): the clone is near-instant and uses no
-extra space until files actually diverge. Non-reflink filesystems fall back to a full recursive copy.
+A full copy has independent `.git`, independent branches, and every gitignored/untracked file already
+in place. The cost is disk and copy time — which on APFS (macOS) and reflink filesystems (Linux) kage
+sidesteps with a copy-on-write clone: near-instant, no extra space until files actually change. Other
+filesystems fall back to a plain recursive copy.
 
 ## Install
 
 ```bash
-# npm
-npm install -g pi-kage     # then use `kage` anywhere
-npx pi-kage                # or run without installing
-
-# pnpm
-pnpm add -g pi-kage
-pnpm dlx pi-kage           # or run without installing
+npm install -g pi-kage      # or: pnpm add -g pi-kage
+npx pi-kage                 # run without installing
 
-# or install script (no npm needed — kage is a single, zero-dependency Node script)
+# install script (single zero-dependency Node script → ~/.local/bin)
 curl -fsSL https://raw.githubusercontent.com/kid7st/kage/main/install.sh | sh
 ```
 
-The install script drops the single `kage` file into `~/.local/bin` (override with `KAGE_BIN_DIR`,
-pin a version with `KAGE_VERSION`). kage has **no dependencies** — it only needs Node, git, and pi.
+Requires **git**, [**pi**](https://github.com/earendil-works), and **Node ≥ 18** on your `PATH`.
+kage has no runtime dependencies.
 
 From source:
 
 ```bash
 git clone https://github.com/kid7st/kage
-cd kage && npm install && npm link   # `npm install` builds bin/kage.mjs from src/ (TypeScript)
+cd kage && npm install && npm link   # npm install builds bin/kage.mjs from src/
 ```
 
-Requires **git**, [**pi**](https://github.com/earendil-works), and **Node ≥ 18** on your `PATH`.
+## Commands
 
-## Lifecycle
+| 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 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 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 --help` / `--version` | anywhere | Usage / version. |
 
-```
-  origin repo (you)                         shadow clone (independent copy)
-  ─────────────────                         ──────────────────────────────
-  $ kage --name fix-login   ─copy + history─►  ../my-app--fix-login
-                                              $ pi      (fresh session; origin history resumable)
-                                                · git switch -c fix-login
-                                                · edit / commit / push / open PR
-                                                · quit pi
-  $ kage finish fix-login   ◄─new sessions──  (the clone's .jsonl, copied back)
-        · safety check (committed? pushed?)
-        · merge the clone's new sessions into ~/.pi
-        · delete the clone folder
-  code arrives via the merged GitHub PR ✓
-```
+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.
 
-## Usage
+### Other agents (Claude Code, Codex)
 
-```bash
-cd ~/code/my-app
-
-kage                       # clone . → ../my-app--kage-<ts>, open a fresh pi (origin history resumable)
-kage --name fix-login      # name the clone folder: ../my-app--fix-login
-kage /path/to/other-repo   # clone a different repo (path defaults to cwd)
-
-# back in the origin after you quit the clone's pi:
-kage                       # no args inside a repo with clones -> interactive menu
-kage status                # status dashboard: branch · dirty · ahead/behind · safe-to-clean
-kage status --pr           # also show PR state (via gh)
-kage finish fix-login      # check → merge the clone's new sessions back → delete the clone
-kage finish fix-login --pr # push the branch + open a PR (via gh), then finish
-kage finish --force        # skip the uncommitted/unpushed guard
-kage rm old-experiment     # discard a clone without merging (refuses if it has local-only work)
-
-# inside a clone, to retrieve a non-git file (e.g. a generated .env):
-kage pull .env config/local.json
-```
-
-With no arguments inside a repo that already has clones, `kage` shows an interactive picker: create a
-new clone, or select an existing one to **enter** (`pi -c`), **finish**, or **remove**. `finish` and `rm`
-show the same picker when you have multiple clones and don't name one.
+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.
 
 ### Shell integration (optional)
 
@@ -120,84 +91,54 @@ show the same picker when you have multiple clones and don't name one.
 eval "$(kage shell-init)"   # add to ~/.zshrc or ~/.bashrc
 ```
 
-This wraps `kage` so that `finish`/`rm` run from inside a clone **cd you back to the origin**
-automatically (a CLI can't change its parent shell's directory otherwise), and adds tab completion
-for subcommands and clone names.
-
-### Commands
-
-| Command | Run from | What it does |
-|---|---|---|
-| `kage [path] [--name x]` | origin repo | Copy the repo to `../<repo>--<name>` (default `kage-<ts>`), copy the origin's 5 most recent pi sessions into the clone (resumable there, never replayed), and launch a **fresh** `pi` session. `--name` only names the folder — kage never creates a branch. With no args (and existing clones) it opens an interactive picker. |
-| `kage status [--pr]` | origin repo | Status dashboard of clones: branch, dirty/clean, ahead/behind upstream, and a “safe to clean” flag. `--pr` adds PR state via `gh`. (`kage list` is a kept alias.) |
-| `kage finish [name] [--force] [--push] [--pr]` | origin, inside the clone, or anywhere with a clone path | Refuse if the clone has uncommitted or unpushed work (`--force` overrides), merge the clone's **new** sessions back (copied-in origin history is skipped), then delete the clone. `--push` pushes the branch first; `--pr` pushes and opens a PR via `gh`. Auto-selects / prompts when there are several. |
-| `kage rm [name] [--force]` | origin, inside the clone, or anywhere with a clone path | Discard a clone **without** merging memory. Refuses if it has local-only work unless `--force`. For abandoned experiments. `name` may be a clone name (run from the repo) or a path to the clone folder (works from anywhere). |
-| `kage pull <path...>` | inside a clone | Copy specific files/dirs (even gitignored ones) back to the origin at the same relative path. |
-| `kage shell-init` | shell rc | Print a shell wrapper (cd-back after `finish`/`rm`) + tab completion. Use `eval "$(kage shell-init)"`. |
-| `kage --help` / `--version` | anywhere | Usage / version. |
+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.
 
 ## How it works
 
-Four invariants keep parallel work safe and lossless:
-
-1. **Isolation** — a clone is a full independent copy with its own `.git`. kage **doesn't create a
-   branch**: the clone stays on the origin's current branch and kage stays out of git flow entirely,
-   so you decide your own branching/PR workflow inside the clone (instruct the agent via your
-   `AGENTS.md`).
-2. **Code flows back via git, never the working tree.** With a remote you push the branch and merge a
-   PR. With **no remote**, `finish` fetches the clone's branch into the origin's git as a local
-   `kage/<name>-<sha>` branch (origin's working tree untouched — `git merge` it when you like; the short
-   sha keeps the ref unique so reusing a name never collides). kage never copies the clone's working
-   tree onto the origin — that would re-create the collisions it avoids — so `finish` refuses to delete
-   **uncommitted** work, which a fetch can't preserve.
-3. **Memory flows through `~/.pi`, never replayed.** On create, the origin's 5 most recent session
-   `.jsonl` files are copied into the clone — `pi`'s resume picker surfaces them, but the clone opens a
-   **fresh** session (kage never replays turns or fakes a resumed conversation). On `finish`, sessions
-   the clone created are copied back whole; an unchanged copied-in session adds nothing; and a
-   copied-in session you *resumed and added to* comes back as a **new, self-contained** session — so
-   the origin's original session (the leaf pi would resume) is never mutated and your turns aren't lost.
-4. **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.
-
-With a remote configured, `finish` nudges you to push first (so PR-flow mistakes surface) unless you
-pass `--push` / `--pr` / `--force`.
-
-## Notes & caveats
-
-- The copy is a snapshot of the origin's **current** state, **including uncommitted changes**.
-- **Submodules**: a submodule's `.git` pointer is an absolute path and breaks on copy — run
+- **Isolation.** A clone is a full independent copy with its own `.git`. kage does **not** create a
+  branch — the clone stays on the origin's current branch and stays out of git flow, so you own the
+  branching/PR workflow inside the clone (tell the agent via your `AGENTS.md`).
+- **Code flows back via git, never the working tree.** With a remote: push the branch, merge the PR.
+  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 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`.)
+- **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.
+
+## Notes
+
+- 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.
-- Non-APFS / non-reflink filesystems fall back to a full (heavier) copy.
-- Session storage is assumed at `~/.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
 
-The CLI and its tests are written in TypeScript and compiled with `tsc`:
+The CLI is TypeScript compiled to a single zero-dependency file:
 
-- `src/kage.mts` → `bin/kage.mjs` — a single, zero-runtime-dependency file (the only thing the
-  install script + npm package ship).
-- `test/kage.test.mts` → `dist/kage.test.mjs` — black-box `node:test` smoke tests that spawn the
-  built CLI (compiled to `dist/` so they run on every Node in CI, no TS loader needed).
-
-`bin/` and `dist/` are build artifacts — both gitignored. `bin/` is produced on `npm install`
-(via `prepare`), so `npm link` from a clone just works.
-
-Linting/formatting is handled by [Biome](https://biomejs.dev) — a dev-only dependency that never
-ships in the package, so the zero-runtime-dependency artifact is unaffected.
-
-```bash
-npm run build    # tsc: src/kage.mts -> bin/kage.mjs
-npm run format   # biome: auto-format + safe lint fixes
-npm run lint     # biome (lint + format check) + tsc type check (src + test)
-npm test         # build CLI + tests, then run node:test smoke tests (temp repos, no network)
-```
+- `src/kage.mts` → `bin/kage.mjs` (the only thing shipped)
+- `test/kage.test.mts` → `dist/` — black-box `node:test` smoke tests that spawn the built CLI
 
-Releases publish automatically: bump `version` in `package.json`, then
+`bin/` and `dist/` are gitignored build artifacts; `bin/` is produced on `npm install` (via `prepare`),
+so `npm link` from a clone just works. Linting/formatting is [Biome](https://biomejs.dev) (dev-only).
 
 ```bash
-git tag vX.Y.Z && git push origin main vX.Y.Z
+npm run build    # tsc: src/kage.mts → bin/kage.mjs
+npm run lint     # biome + tsc type check
+npm test         # build + node:test smoke tests (temp repos, no network)
 ```
 
+Releases: bump `version` in `package.json`, then `git tag vX.Y.Z && git push origin main vX.Y.Z`.
 CI runs lint + tests and `npm publish --provenance` on any `v*` tag.
 
 ## License

package/README.zh-CN.md

@@ -0,0 +1,135 @@
+# kage 🥷
+
+[![CI](https://github.com/kid7st/kage/actions/workflows/ci.yml/badge.svg)](https://github.com/kid7st/kage/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-kage)](https://www.npmjs.com/package/pi-kage)
+[![license](https://img.shields.io/npm/l/pi-kage)](./LICENSE)
+
+> 影分身の術 —— 给你的 git 仓库来一发影分身。· [English](./README.md)
+
+<p align="center"><img src="./assets/demo.svg" alt="kage demo" width="100%"></p>
+
+在同一个仓库上同时跑多个 AI coding agent。让两个 agent 指向同一个 checkout，它们就会抢同一个工作区
+——改同样的文件、撞同样的分支、踩到彼此未提交的改动。kage 给每个 session 一份**独立的完整副本**，放在
+同级目录里，从根本上避免冲突。
+
+```bash
+npm install -g pi-kage
+cd my-app
+kage            # 🥷 复制 → ../my-app--kage-<ts>，打开一个全新的 pi
+#   ...提交、push、开 PR、退出 pi...
+kage finish     # 💨 把分身的 session 合并回来，删掉分身
+```
+
+代码通过 git 回流（一个 PR，或者 fetch 分支）；agent 的 session 记忆通过它自己的 session 存储（`~/.pi`、
+`~/.claude` 或 `~/.codex`）回流。kage 从不把工作区复制回原仓库 —— 这正是它存在的意义。
+
+## 为什么用完整副本，而不是 `git worktree`？
+
+[`git worktree`](https://git-scm.com/docs/git-worktree) 能给你第二个工作目录，但所有 worktree 共享同一个
+`.git`：两个 agent 没法 checkout 同一个分支，stash / refs / index 也都是共享的。而且 worktree 是干净的
+checkout —— 没有 `node_modules`、`.env`、build 缓存，每个都得先跑一遍环境初始化。
+
+完整副本则有独立的 `.git`、独立的分支，所有被 gitignore 或未跟踪的文件也都已就位。代价是磁盘和复制时间
+—— 而在 APFS（macOS）和支持 reflink 的文件系统（Linux）上，kage 用写时复制（copy-on-write）绕开了这个代价：
+几乎瞬间完成，文件真正发生改动前不占额外空间。其它文件系统则退化为普通的递归复制。
+
+## 安装
+
+```bash
+npm install -g pi-kage      # 或：pnpm add -g pi-kage
+npx pi-kage                 # 不安装直接运行
+
+# 安装脚本（单个零依赖的 Node 脚本 → ~/.local/bin）
+curl -fsSL https://raw.githubusercontent.com/kid7st/kage/main/install.sh | sh
+```
+
+需要 `PATH` 上有 **git**、[**pi**](https://github.com/earendil-works) 和 **Node ≥ 18**。
+kage 没有任何运行时依赖。
+
+从源码安装：
+
+```bash
+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 status [--pr]` | 原仓库 | 仪表盘：分支、是否有改动、ahead/behind、是否「可安全清理」。`--pr` 通过 `gh` 附带 PR 状态。 |
+| `kage finish [name] [--force] [--push] [--pr]` | 原仓库 / 分身内 | 若分身有未提交或未 push 的改动则拒绝，把它**新产生**的 session 合并回来，再删除它。`--push` 先 push 分支；`--pr` push 并通过 `gh` 开 PR；`--force` 跳过检查。 |
+| `kage rm [name] [--force]` | 原仓库 / 分身内 | **不**合并记忆地丢弃一个分身。若有仅存在于本地的工作则拒绝，除非加 `--force`。 |
+| `kage pull <path...>` | 分身内 | 把指定文件/目录（包括被 gitignore 的，比如生成的 `.env`）按相同相对路径拷回原仓库。 |
+| `kage shell-init` | shell 配置 | shell 包装函数（`finish`/`rm` 后自动 cd 回原仓库）+ tab 补全。用 `eval "$(kage shell-init)"`。 |
+| `kage --help` / `--version` | 任意位置 | 用法 / 版本。 |
+
+在已有分身的仓库里直接运行 `kage`，会弹出交互选择器：新建一个分身，或对已有分身执行 **进入** / **finish** /
+**删除**。当有多个分身又没指定名字时，`finish` 和 `rm` 也会弹出同样的选择器。
+
+### 其它 agent（Claude Code、Codex）
+
+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。
+
+### Shell 集成（可选）
+
+```bash
+eval "$(kage shell-init)"   # 加到 ~/.zshrc 或 ~/.bashrc
+```
+
+在分身内运行 `finish`/`rm` 会删掉你 shell 当前所在的目录。这个包装函数会自动把你 cd 回原仓库（否则 CLI
+没法改变父 shell 的目录），并为子命令和分身名加上 tab 补全。
+
+## 工作原理
+
+- **隔离。** 一个分身是带独立 `.git` 的完整副本。kage **不**建分支 —— 分身停在原仓库当前分支上，且完全不
+  介入 git 流程，所以分身内的分支 / PR 工作流由你自己决定（通过 `AGENTS.md` 告诉 agent）。
+- **代码只经由 git 回流，绝不经过工作区。** 有 remote 时：push 分支、合并 PR。没有 remote 时：`finish` 会把
+  分身的分支 fetch 进原仓库的 git，存成本地分支 `kage/<name>-<sha>`（原仓库工作区不动 —— 你想合并时再
+  `git merge`）。由于 fetch 无法保留未提交的改动，`finish` 拒绝删除有改动的分身，除非加 `--force`。
+- **记忆经由该 agent 自己的 session 存储回流，绝不重放。** 创建时拷入原仓库最近 5 个该 agent 的 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`。）
+- **对 kage 而言原仓库是只读的。** 它只往外复制、只写 session 记忆 —— 即使原仓库里另有一个 session 正活跃，
+  它也绝不碰原仓库的工作区。
+
+## 注意事项
+
+- 副本是原仓库**当前**状态的快照，包含未提交的改动。
+- **Submodule**：submodule 的 `.git` 是绝对路径，复制后会失效 —— 在分身里跑一次
+  `git submodule update --init`。
+- kage 从每个 agent **自己**存 session 的地方去读，尊重该 agent 自己的配置变量 ——
+  `PI_CODING_AGENT_DIR`（pi）、`CLAUDE_CONFIG_DIR`（Claude Code）、`CODEX_HOME`（Codex）—— 这样
+  kage 和 agent 永远指向同一个位置。
+
+## 开发
+
+CLI 用 TypeScript 写，编译成单个零依赖文件：
+
+- `src/kage.mts` → `bin/kage.mjs`（唯一发布的文件）
+- `test/kage.test.mts` → `dist/` —— 启动编译后 CLI 的黑盒 `node:test` 冒烟测试
+
+`bin/` 和 `dist/` 是被 gitignore 的构建产物；`bin/` 在 `npm install` 时（通过 `prepare`）生成，所以从克隆出来
+的仓库直接 `npm link` 即可。代码检查 / 格式化用 [Biome](https://biomejs.dev)（仅开发依赖）。
+
+```bash
+npm run build    # tsc: src/kage.mts → bin/kage.mjs
+npm run lint     # biome + tsc 类型检查
+npm test         # 构建 + node:test 冒烟测试（临时仓库，不联网）
+```
+
+发布：在 `package.json` 里更新 `version`，然后 `git tag vX.Y.Z && git push origin main vX.Y.Z`。
+任何 `v*` tag 都会触发 CI 跑 lint + 测试并执行 `npm publish --provenance`。
+
+## License
+
+[MIT](./LICENSE)

package/bin/kage.mjs

@@ -16,7 +16,7 @@
  *   4. The origin is read-only to kage — it only copies out and writes session memory.
  *
  * Commands:
- *   kage [path] [--name x]                           clone repo + launch a fresh pi (no args: interactive)
+ *   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)
@@ -24,13 +24,12 @@
  */
 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.7"; // keep in sync with package.json (enforced by test)
+const VERSION = "0.4.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 +63,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);
@@ -185,7 +184,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;
 }
@@ -322,14 +321,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)
@@ -352,123 +351,254 @@ async function pickClone(action, name) {
         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;
+                /* ignore */
             }
-            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) {
             try {
-                have.add(JSON.parse(l).id);
+                rmSync(dirFor(cloneDir), { recursive: true, force: true });
             }
             catch {
                 /* ignore */
             }
-        }
-        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;
+}
+/**
+ * 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.
+ */
+const codexStore = {
+    id: "codex",
+    importHistory: () => 0,
+    mergeBack: () => 0,
+    discard: () => { },
+    hasActivity(cwd) {
+        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
@@ -490,15 +620,57 @@ function leaveClone(originRepo) {
     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`));
 }
-function launchPi(cwd, args) {
-    const r = spawnSync("pi", args, { cwd, stdio: "inherit" });
+// 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.
+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("pi not found (make sure it is installed and on your PATH)");
-        die(`failed to launch pi: ${err.message}`);
+            die(`${cli.bin} not found (make sure it is installed and on your PATH)`);
+        die(`failed to launch ${cli.bin}: ${err.message}`);
     }
 }
+/** 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(`${bin} not found (make sure it is installed and on your PATH)`);
+        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) {
+    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];
+    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];
+    }
+    if (chosen?.cli)
+        launchCli(chosen.cli, cloneDir, chosen.cli.resumeArgs);
+}
 // ── subcommands ───────────────────────────────────────────────────────────────
 async function cmdNew(argv) {
     const { positional, flags } = parseArgs(argv);
@@ -523,9 +695,9 @@ async function cmdNew(argv) {
                 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)", "Finish (merge memory & remove)", "Remove (discard)", "Cancel"]);
                 if (act === 0)
-                    return launchPi(clone.dir, ["-c"]);
+                    return enterClone(clone.dir);
                 if (act === 1)
                     return cmdFinish([clone.name]);
                 if (act === 2)
@@ -554,11 +726,19 @@ async function cmdNew(argv) {
     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)
+        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,
@@ -573,9 +753,23 @@ async function cmdNew(argv) {
         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, []);
+    // Launch mode: --no-launch (just build), --open <cmd> (open + return), else spawn the CLI.
+    if (boolFlag(flags, "no-launch"))
+        return;
+    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 pi. To finish: ${paint.bold(`kage finish ${safe}`)}`);
+    info(`↩︎  left the clone's ${agent.cli.bin}. To finish: ${paint.bold(`kage finish ${safe}`)}`);
 }
 async function cmdFinish(argv) {
     const { positional, flags } = parseArgs(argv);
@@ -641,7 +835,9 @@ 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);
+    let n = 0;
+    for (const a of AGENTS)
+        n += a.store.mergeBack(clone.dir, originRepo);
     try {
         process.chdir(originRepo);
     }
@@ -675,12 +871,8 @@ async function cmdRm(argv) {
     catch {
         /* ignore */
     }
-    try {
-        rmSync(sessionDirFor(clone.dir), { recursive: true, force: true });
-    }
-    catch {
-        /* ignore */
-    }
+    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)
@@ -705,7 +897,7 @@ function cmdList(argv) {
         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 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 = [];
@@ -817,7 +1009,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 repo + launch a fresh agent (default: pi)
+                                                       --open <cmd> | --no-launch: open it yourself instead
                                                        (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
@@ -834,6 +1027,9 @@ 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
   --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)
@@ -854,8 +1050,11 @@ Examples:
 
   kage pull .env                # inside a clone: copy a gitignored file back to the origin
 
-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            default agent to launch when --agent is omitted (default: pi)
+  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 +1062,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 +1069,7 @@ async function main() {
             return cmdRm(rest);
         case "pull":
             return cmdPull(rest);
-        case "shell-init":
-        case "completion": {
+        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,6 +1,6 @@
 {
   "name": "pi-kage",
-  "version": "0.3.7",
+  "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",
   "keywords": [
     "pi",