pi-kage 0.3.8 → 0.4.0

package/README.md

@@ -22,7 +22,8 @@ kage finish     # 💨 merge the clone's sessions back, delete the clone
 ```
 
 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`?
 
@@ -60,8 +61,8 @@ cd kage && npm install && npm link   # npm install builds bin/kage.mjs from src/
 
 | 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 [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. |
@@ -72,6 +73,18 @@ Run bare `kage` inside a repo that already has clones to get an interactive pick
 or **enter** / **finish** / **remove** an existing one. `finish` and `rm` show the same picker when you
 have several clones and don't name one.
 
+### Other agents (Claude Code, Codex)
+
+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)
 
 ```bash
@@ -91,10 +104,12 @@ 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, 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.
 
@@ -103,7 +118,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

@@ -20,8 +20,8 @@ kage            # 🥷 复制 → ../my-app--kage-<ts>，打开一个全新的 p
 kage finish     # 💨 把分身的 session 合并回来，删掉分身
 ```
 
-代码通过 git 回流（一个 PR，或者 fetch 分支）；agent 的 session 记忆通过 `~/.pi` 回流。kage 从不把工作区
-复制回原仓库 —— 这正是它存在的意义。
+代码通过 git 回流（一个 PR，或者 fetch 分支）；agent 的 session 记忆通过它自己的 session 存储（`~/.pi`、
+`~/.claude` 或 `~/.codex`）回流。kage 从不把工作区复制回原仓库 —— 这正是它存在的意义。
 
 ## 为什么用完整副本，而不是 `git worktree`？
 
@@ -57,8 +57,8 @@ cd kage && npm install && npm link   # npm install 会从 src/ 编译出 bin/kag
 
 | 命令 | 在哪运行 | 作用 |
 |---|---|---|
-| `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 [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`）按相同相对路径拷回原仓库。 |
@@ -68,6 +68,16 @@ cd kage && npm install && npm link   # npm install 会从 src/ 编译出 bin/kag
 在已有分身的仓库里直接运行 `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
@@ -84,9 +94,11 @@ 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 是
+  例外 —— 它的 session 在一个 sqlite 索引的全局 store 里，kage 无法干净搬迁，所以不管理 Codex 记忆；Codex
+  历史用 `codex resume --all` 查。详见 `docs/multi-agent-design.md`。）
 - **对 kage 而言原仓库是只读的。** 它只往外复制、只写 session 记忆 —— 即使原仓库里另有一个 session 正活跃，
   它也绝不碰原仓库的工作区。
 
@@ -95,7 +107,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

@@ -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.8"; // 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.8",
+  "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",