@childclm/codexx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 clm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# codexx
+
+`codexx` 是一个跑在 `Codex CLI` 外层的跨平台启动器，目标是把这几件事收进一个终端入口里：
+
+- 项目级主线 / 分支会话管理
+- 多 `provider` / `apiKey` 切换
+- 基于 Codex 原生会话的恢复、分叉、删除
+
+它不替代 `codex`，而是建立在 `codex` 之上。
+
+## 特性
+
+- 跨平台：Node.js 实现，目标支持 macOS 与 Windows
+- 项目隔离：项目元数据保存在 `<project>/.codexx/`
+- Provider 全局共享：全局配置保存在用户配置目录
+- 会话树：支持主线会话、分支会话、父子关系
+- 恢复与分叉：底层直接调用 `codex resume` / `codex fork`
+
+## 前置要求
+
+- 已安装 Node.js `>=18`
+- 已安装并可运行 `codex`
+
+先确认：
+
+```bash
+node -v
+codex --version
+```
+
+## 安装
+
+### 本地开发安装
+
+```bash
+npm install -g .
+```
+
+### 发布后安装
+
+如果包名可用并已发布到 npm：
+
+```bash
+npm install -g @childclm/codexx
+```
+
+## 使用
+
+在具体项目目录中运行：
+
+```bash
+codexx
+```
+
+常见子命令：
+
+```bash
+codexx init
+codexx list
+codexx providers
+```
+
+## 存储位置
+
+### Codex 原生数据
+
+这些数据由 `codex` 自己维护：
+
+- `~/.codex/sessions/`
+- `~/.codex/session_index.jsonl`
+- `~/.codex/history.jsonl`
+
+### codexx 全局数据
+
+macOS / Linux:
+
+```text
+~/.config/codexx/providers.json
+```
+
+Windows:
+
+```text
+%APPDATA%/codexx/providers.json
+```
+
+### codexx 项目数据
+
+```text
+<project>/.codexx/project.json
+<project>/.codexx/sessions.json
+```
+
+## 发布前检查
+
+```bash
+npm run check
+npm run pack:dry
+npm run publish:dry
+```
+
+## 当前状态
+
+截至 2026-07-17：
+
+- 本地 `npm publish --dry-run` 可通过
+- 已切换为 scoped 包名 `@childclm/codexx`
+- 如果要正式发布，建议先执行：
+
+```bash
+npm view @childclm/codexx name version
+```
+
+首次正式发布 scoped 包时，使用：
+
+```bash
+npm publish --access public
+```
+
+## License
+
+MIT

package/bin/codexx.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require("../src/index");

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@childclm/codexx",
+  "version": "0.1.0",
+  "description": "Cross-platform launcher for Codex CLI with project-scoped session trees and provider switching.",
+  "main": "src/index.js",
+  "bin": {
+    "codexx": "bin/codexx.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "preferGlobal": true,
+  "scripts": {
+    "start": "node bin/codexx.js",
+    "check": "node --check src/index.js",
+    "test": "node bin/codexx.js --help",
+    "pack:dry": "npm pack --dry-run",
+    "publish:dry": "npm publish --dry-run"
+  },
+  "keywords": [
+    "codex",
+    "cli",
+    "openai",
+    "session-manager",
+    "terminal",
+    "cross-platform"
+  ],
+  "author": "clm",
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,1176 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+const crypto = require("crypto");
+const { spawn, spawnSync } = require("child_process");
+
+const APP_NAME = "codexx";
+const HOME = os.homedir();
+const CONFIG_ROOT =
+  process.platform === "win32"
+    ? path.join(
+        process.env.APPDATA || path.join(HOME, "AppData", "Roaming"),
+        APP_NAME,
+      )
+    : path.join(HOME, ".config", APP_NAME);
+const PROVIDERS_FILE = path.join(CONFIG_ROOT, "providers.json");
+const SETTINGS_FILE = path.join(CONFIG_ROOT, "settings.json");
+const CODEX_HOME = path.join(HOME, ".codex");
+const CODEX_SESSIONS_DIR = path.join(CODEX_HOME, "sessions");
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file, data) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+}
+
+function normalizePath(p) {
+  return path.resolve(p);
+}
+
+function md5(text) {
+  return crypto.createHash("md5").update(String(text)).digest("hex");
+}
+
+function getProjectRoot(cwd = process.cwd()) {
+  const out = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd,
+    encoding: "utf8",
+  });
+  if (out.status === 0) {
+    const root = (out.stdout || "").trim();
+    if (root) return normalizePath(root);
+  }
+  return normalizePath(cwd);
+}
+
+function isHomeProject(root) {
+  return normalizePath(root) === normalizePath(HOME);
+}
+
+function ensureUsableProject(cwd = process.cwd()) {
+  const root = getProjectRoot(cwd);
+  if (isHomeProject(root)) {
+    return {
+      ok: false,
+      root,
+      reason:
+        "当前目录落在 HOME 根目录，容易把不相关会话全搅一起。请先 cd 到具体项目目录再运行 codexx。",
+    };
+  }
+  return { ok: true, root };
+}
+
+function getProjectPaths(cwd = process.cwd()) {
+  const root = getProjectRoot(cwd);
+  const stateDir = path.join(root, ".codexx");
+  return {
+    root,
+    stateDir,
+    projectFile: path.join(stateDir, "project.json"),
+    sessionsFile: path.join(stateDir, "sessions.json"),
+  };
+}
+
+function loadProviders() {
+  return readJson(PROVIDERS_FILE, {
+    default: null,
+    providers: [],
+  });
+}
+
+function loadSettings() {
+  return readJson(SETTINGS_FILE, {
+    codexCommand: "codex",
+  });
+}
+
+function loadProject(cwd = process.cwd()) {
+  const { root, projectFile } = getProjectPaths(cwd);
+  return readJson(projectFile, {
+    projectId: md5(root),
+    name: path.basename(root),
+    root,
+    defaultProvider: null,
+    provider: null,
+    mainSessionId: null,
+    lastSessionId: null,
+  });
+}
+
+function saveProject(state, cwd = process.cwd()) {
+  const { projectFile } = getProjectPaths(cwd);
+  ensureDir(path.dirname(projectFile));
+  writeJson(projectFile, state);
+}
+
+function loadProjectSessionsMeta(cwd = process.cwd()) {
+  const { sessionsFile } = getProjectPaths(cwd);
+  return readJson(sessionsFile, { sessions: [] });
+}
+
+function saveProjectSessionsMeta(data, cwd = process.cwd()) {
+  const { sessionsFile } = getProjectPaths(cwd);
+  ensureDir(path.dirname(sessionsFile));
+  writeJson(sessionsFile, data);
+}
+
+function detectCodex() {
+  const settings = loadSettings();
+  return settings.codexCommand || "codex";
+}
+
+function codexPath() {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const out = spawnSync(finder, ["codex"], { encoding: "utf8" });
+  return (out.stdout || "").trim().split(/\r?\n/)[0] || "";
+}
+
+function clearScreen() {
+  process.stdout.write("\x1b[2J\x1b[0f");
+}
+
+function prompt(rl, text) {
+  return new Promise((resolve) => rl.question(text, resolve));
+}
+
+function setRawMode(enabled) {
+  if (typeof process.stdin.setRawMode === "function") {
+    process.stdin.setRawMode(enabled);
+  }
+}
+
+function flushStdinBuffer() {
+  let chunk;
+  do {
+    chunk = process.stdin.read();
+  } while (chunk !== null);
+}
+
+async function askText(rl, label) {
+  setRawMode(false);
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  flushStdinBuffer();
+  const answer = await prompt(rl, label);
+  setRawMode(true);
+  return answer;
+}
+
+async function pause(rl, text = "按回车继续...") {
+  await askText(rl, `\n${text}`);
+}
+
+function renderMenu(title, items, selected, footer = "") {
+  clearScreen();
+  console.log(title);
+  console.log("=".repeat(Math.max(title.length, 18)));
+  items.forEach((item, index) => {
+    const prefix = index === selected ? "❯" : " ";
+    console.log(`${prefix} [${index + 1}] ${item}`);
+  });
+  if (footer) console.log(footer);
+}
+
+function renderContextMenu(title, contextLines, items, selected, footer = "") {
+  clearScreen();
+  console.log(title);
+  console.log("=".repeat(Math.max(title.length, 18)));
+  for (const line of contextLines) {
+    console.log(line);
+  }
+  if (contextLines.length) console.log("");
+  items.forEach((item, index) => {
+    const prefix = index === selected ? "❯" : " ";
+    console.log(`${prefix} [${index + 1}] ${item}`);
+  });
+  if (footer) console.log(footer);
+}
+
+function readKey() {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    const onKeypress = (_, key) => {
+      if (!key) return;
+      if (Date.now() - startedAt < 35) return;
+      process.stdin.off("keypress", onKeypress);
+      if (key.name === "up") return resolve("up");
+      if (key.name === "down") return resolve("down");
+      if (key.name === "return") return resolve("enter");
+      if (key.name === "escape") return resolve("escape");
+      if (key.ctrl && key.name === "c") return resolve("exit");
+      if (/^[1-9]$/.test(key.sequence || "")) {
+        return resolve({ type: "digit", value: Number(key.sequence) });
+      }
+      return resolve("other");
+    };
+    process.stdin.on("keypress", onKeypress);
+  });
+}
+
+async function selectIndex(title, items, footer = "") {
+  if (!items.length) return null;
+  let selected = 0;
+  let showPicked = false;
+  while (true) {
+    const effectiveFooter = showPicked
+      ? `${footer} · 当前选中: [${selected + 1}] ${items[selected]}`
+      : footer;
+    renderMenu(title, items, selected, effectiveFooter);
+    const key = await readKey();
+    if (typeof key === "object" && key?.type === "digit") {
+      const idx = key.value - 1;
+      if (idx >= 0 && idx < items.length) {
+        selected = idx;
+        showPicked = true;
+      }
+      continue;
+    }
+    if (key === "up") {
+      selected = (selected - 1 + items.length) % items.length;
+      showPicked = false;
+    } else if (key === "down") {
+      selected = (selected + 1) % items.length;
+      showPicked = false;
+    }
+    else if (key === "enter") {
+      clearScreen();
+      return selected;
+    } else if (key === "escape" || key === "exit") {
+      clearScreen();
+      return null;
+    }
+  }
+}
+
+async function selectIndexWithContext(title, contextLines, items, footer = "") {
+  if (!items.length) return null;
+  let selected = 0;
+  let showPicked = false;
+  while (true) {
+    const effectiveFooter = showPicked
+      ? `${footer} · 当前选中: [${selected + 1}] ${items[selected]}`
+      : footer;
+    renderContextMenu(title, contextLines, items, selected, effectiveFooter);
+    const key = await readKey();
+    if (typeof key === "object" && key?.type === "digit") {
+      const idx = key.value - 1;
+      if (idx >= 0 && idx < items.length) {
+        selected = idx;
+        showPicked = true;
+      }
+      continue;
+    }
+    if (key === "up") {
+      selected = (selected - 1 + items.length) % items.length;
+      showPicked = false;
+    } else if (key === "down") {
+      selected = (selected + 1) % items.length;
+      showPicked = false;
+    }
+    else if (key === "enter") {
+      clearScreen();
+      return selected;
+    } else if (key === "escape" || key === "exit") {
+      clearScreen();
+      return null;
+    }
+  }
+}
+
+function isWithinProject(targetPath, projectRoot) {
+  const normalizedTarget = normalizePath(targetPath);
+  const normalizedProject = normalizePath(projectRoot);
+  return (
+    normalizedTarget === normalizedProject ||
+    normalizedTarget.startsWith(normalizedProject + path.sep)
+  );
+}
+
+function walkFiles(dir, acc = []) {
+  if (!fs.existsSync(dir)) return acc;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkFiles(full, acc);
+    else if (entry.isFile() && entry.name.endsWith(".jsonl")) acc.push(full);
+  }
+  return acc;
+}
+
+function parseSessionMeta(file) {
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    const firstLine = text.split(/\r?\n/, 1)[0];
+    if (!firstLine) return null;
+    const item = JSON.parse(firstLine);
+    if (item.type !== "session_meta" || !item.payload) return null;
+    return {
+      id: item.payload.id,
+      cwd: item.payload.cwd,
+      createdAt: item.payload.timestamp || item.timestamp,
+      modelProvider: item.payload.model_provider || "",
+      originator: item.payload.originator || "",
+      file,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function listOfficialProjectSessions(projectRoot) {
+  const files = walkFiles(CODEX_SESSIONS_DIR);
+  return files
+    .map(parseSessionMeta)
+    .filter(Boolean)
+    .filter((item) => item.cwd && isWithinProject(item.cwd, projectRoot))
+    .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+}
+
+function hasOfficialSession(sessionId, projectRoot) {
+  return listOfficialProjectSessions(projectRoot).some(
+    (item) => item.id === sessionId,
+  );
+}
+
+function buildCodexEnv(provider) {
+  return {
+    OPENAI_API_KEY: provider.apiKey,
+    OPENAI_BASE_URL: provider.baseUrl || process.env.OPENAI_BASE_URL,
+  };
+}
+
+function runCodex(args, env, cwd = process.cwd()) {
+  return new Promise((resolve, reject) => {
+    const cmd = detectCodex();
+    const child = spawn(cmd, args, {
+      cwd,
+      stdio: "inherit",
+      env: { ...process.env, ...env },
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 0));
+  });
+}
+
+async function maybeLinkLatestSession(projectRoot, providerName, startedAtMs) {
+  const sessions = listOfficialProjectSessions(projectRoot);
+  const latest = sessions.find(
+    (item) => new Date(item.createdAt).getTime() >= startedAtMs - 5000,
+  );
+  return latest ? latest.id : null;
+}
+
+function maskKey(key) {
+  if (!key) return "(空)";
+  if (key.length <= 8) return `${key.slice(0, 2)}***${key.slice(-2)}`;
+  return `${key.slice(0, 4)}***${key.slice(-4)}`;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function defaultTitle(providerName, kind) {
+  const d = new Date();
+  const pad = (v) => String(v).padStart(2, "0");
+  const local = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+  return `${local} · ${providerName} · ${kind}`;
+}
+
+function upsertSessionMeta(session, cwd = process.cwd()) {
+  const data = loadProjectSessionsMeta(cwd);
+  const idx = data.sessions.findIndex((item) => item.sessionId === session.sessionId);
+  if (idx >= 0) data.sessions[idx] = { ...data.sessions[idx], ...session };
+  else data.sessions.push(session);
+  saveProjectSessionsMeta(data, cwd);
+}
+
+function removeSessionMeta(sessionId, cwd = process.cwd()) {
+  const data = loadProjectSessionsMeta(cwd);
+  data.sessions = data.sessions.filter((item) => item.sessionId !== sessionId);
+  saveProjectSessionsMeta(data, cwd);
+}
+
+function getSessionMeta(sessionId, cwd = process.cwd()) {
+  return loadProjectSessionsMeta(cwd).sessions.find((item) => item.sessionId === sessionId) || null;
+}
+
+function listProjectSessionsWithMeta(cwd = process.cwd()) {
+  const project = loadProject(cwd);
+  const official = listOfficialProjectSessions(project.root);
+  const metaMap = new Map(
+    loadProjectSessionsMeta(cwd).sessions.map((item) => [item.sessionId, item]),
+  );
+  return official.map((session) => {
+    const meta = metaMap.get(session.id) || {};
+    return {
+      sessionId: session.id,
+      createdAt: session.createdAt,
+      updatedAt: meta.updatedAt || session.createdAt,
+      title: meta.title || defaultTitle(meta.provider || "unknown", meta.kind || "main"),
+      kind: meta.kind || "main",
+      parentSessionId: meta.parentSessionId || null,
+      provider: meta.provider || null,
+      isMain: Boolean(meta.isMain),
+      cwd: session.cwd,
+    };
+  }).sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+}
+
+function hydrateProjectMetadata(cwd = process.cwd()) {
+  const project = loadProject(cwd);
+  const data = loadProjectSessionsMeta(cwd);
+  const official = listOfficialProjectSessions(project.root);
+  const officialIds = new Set(official.map((item) => item.id));
+  let changed = false;
+
+  data.sessions = data.sessions
+    .filter((item) => {
+      const keep = officialIds.has(item.sessionId);
+      if (!keep) changed = true;
+      return keep;
+    })
+    .map((item) => {
+      const next = { ...item };
+      if (!next.kind) {
+        next.kind = next.parentSessionId ? "branch" : "main";
+        changed = true;
+      }
+      if (!next.title) {
+        next.title = defaultTitle(next.provider || "unknown", next.kind);
+        changed = true;
+      }
+      if (!next.createdAt) {
+        next.createdAt = next.updatedAt || nowIso();
+        changed = true;
+      }
+      if (!next.updatedAt) {
+        next.updatedAt = next.createdAt || nowIso();
+        changed = true;
+      }
+      if (typeof next.isMain !== "boolean") {
+        next.isMain = next.kind === "main";
+        changed = true;
+      }
+      return next;
+    });
+
+  if (!project.mainSessionId) {
+    const main = data.sessions.find((item) => item.isMain || item.kind === "main");
+    if (main) {
+      project.mainSessionId = main.sessionId;
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    saveProjectSessionsMeta(data, cwd);
+    saveProject(project, cwd);
+  }
+}
+
+function getProviderForSession(sessionId, cwd = process.cwd()) {
+  return getSessionMeta(sessionId, cwd)?.provider || null;
+}
+
+function getCurrentMainSession(projectState, cwd = process.cwd()) {
+  const sessions = listProjectSessionsWithMeta(cwd);
+  if (projectState.mainSessionId) {
+    const hit = sessions.find((item) => item.sessionId === projectState.mainSessionId);
+    if (hit) return hit;
+  }
+  return sessions.find((item) => item.kind === "main" || item.isMain) || null;
+}
+
+function countChildBranches(sessionId, cwd = process.cwd()) {
+  return loadProjectSessionsMeta(cwd).sessions.filter(
+    (item) => item.parentSessionId === sessionId,
+  ).length;
+}
+
+function getChildSessions(sessionId, cwd = process.cwd()) {
+  return listProjectSessionsWithMeta(cwd)
+    .filter((item) => item.parentSessionId === sessionId)
+    .sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+}
+
+function getMainSessions(cwd = process.cwd()) {
+  return listProjectSessionsWithMeta(cwd)
+    .filter((item) => item.kind === "main" || item.isMain || !item.parentSessionId)
+    .sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+}
+
+function formatSessionLabel(session, cwd = process.cwd()) {
+  const childCount = getChildSessions(session.sessionId, cwd).length;
+  const role = session.kind === "branch" ? "branch" : "main";
+  return `${session.title} | ${role} | ${session.provider || "未知 provider"} | 分支:${childCount}`;
+}
+
+async function chooseProviderMenu(rl, projectState, providersState) {
+  if (!providersState.providers.length) return null;
+  const titles = providersState.providers.map((provider) => {
+    const marker =
+      provider.name === (projectState.provider || projectState.defaultProvider)
+        ? " (当前项目)"
+        : "";
+    return `${provider.name}${marker}`;
+  });
+  const idx = await selectIndex(
+    "选择 provider",
+    titles,
+    "↑↓/数字 选择 · Enter 确认 · Esc 返回",
+  );
+  if (idx === null) return null;
+  return providersState.providers[idx];
+}
+
+async function providerManagementMenu(rl, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  while (true) {
+    const projectState = loadProject(cwd);
+    const providersState = loadProviders();
+    const action = await selectIndex(
+      "Provider 管理",
+      ["新增/更新 provider", "切换当前项目 provider", "查看 provider 列表", "删除 provider", "返回"],
+      "↑↓/数字 选择 · Enter 确认 · Esc 返回",
+    );
+    if (action === null || action === 4) return;
+
+    if (action === 0) {
+      clearScreen();
+      console.log("新增/更新 provider");
+      console.log("================");
+      const name = (await askText(rl, "provider 名称: ")).trim();
+      if (!name) {
+        await pause(rl, "名称不能为空，按回车返回...");
+        continue;
+      }
+      const apiKey = (await askText(rl, "api-key: ")).trim();
+      const baseUrl = (await askText(rl, "base url (可空): ")).trim();
+      const modelProvider = (await askText(
+        rl,
+        "codex provider 名称 (可空): ",
+      )).trim();
+      const provider = { name, apiKey, baseUrl, modelProvider };
+      providersState.providers = providersState.providers.filter(
+        (item) => item.name !== name,
+      );
+      providersState.providers.push(provider);
+      if (!providersState.default) providersState.default = name;
+      writeJson(PROVIDERS_FILE, providersState);
+      clearScreen();
+      console.log("已保存 provider:", name);
+      await pause(rl);
+      continue;
+    }
+
+    if (action === 1) {
+      const selected = await chooseProviderMenu(rl, projectState, providersState);
+      if (!selected) continue;
+      projectState.provider = selected.name;
+      projectState.defaultProvider = selected.name;
+      saveProject(projectState, cwd);
+      clearScreen();
+      console.log("当前项目 provider 已切换为:", selected.name);
+      await pause(rl);
+      continue;
+    }
+
+    if (action === 2) {
+      clearScreen();
+      console.log("Provider 列表");
+      console.log("=============");
+      if (!providersState.providers.length) {
+        console.log("(空)");
+      } else {
+        providersState.providers.forEach((item, index) => {
+          console.log(
+            `${index + 1}. ${item.name} | key=${maskKey(item.apiKey)} | base=${item.baseUrl || "(默认)"}`,
+          );
+        });
+      }
+      await pause(rl);
+      continue;
+    }
+
+    if (action === 3) {
+      if (!providersState.providers.length) {
+        clearScreen();
+        console.log("没有可删除的 provider。");
+        await pause(rl);
+        continue;
+      }
+      const idx = await selectIndex(
+        "删除 provider",
+        providersState.providers.map((item) => item.name),
+        "↑↓/数字 选择 · Enter 删除 · Esc 返回",
+      );
+      if (idx === null) continue;
+      const removed = providersState.providers[idx];
+      providersState.providers.splice(idx, 1);
+      if (providersState.default === removed.name) {
+        providersState.default = providersState.providers[0]?.name || null;
+      }
+      writeJson(PROVIDERS_FILE, providersState);
+      if (projectState.provider === removed.name) {
+        projectState.provider = providersState.default;
+        projectState.defaultProvider = providersState.default;
+        saveProject(projectState, cwd);
+      }
+      clearScreen();
+      console.log("已删除 provider:", removed.name);
+      await pause(rl);
+    }
+  }
+}
+
+async function showCurrentStatus(rl, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  const projectState = loadProject(cwd);
+  const providersState = loadProviders();
+  const sessions = listProjectSessionsWithMeta(cwd);
+  clearScreen();
+  console.log("当前状态");
+  console.log("========");
+  console.log("项目 ID:", projectState.projectId);
+  console.log("项目名:", projectState.name);
+  console.log("项目根:", projectState.root);
+  console.log("默认 provider:", projectState.defaultProvider || "(未设置)");
+  console.log("当前 provider:", projectState.provider || "(未设置)");
+  console.log("主线 session:", projectState.mainSessionId || "(无)");
+  console.log("最近 session:", projectState.lastSessionId || "(无)");
+  console.log("provider 数量:", providersState.providers.length);
+  console.log("项目会话数:", sessions.length);
+  console.log("codex 命令:", codexPath() || "(未找到)");
+  await pause(rl);
+}
+
+async function showProjectSessions(rl, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  const sessions = listProjectSessionsWithMeta(cwd);
+  clearScreen();
+  console.log("本项目会话");
+  console.log("==========");
+  if (!sessions.length) {
+    console.log("(空)");
+  } else {
+    sessions.slice(0, 30).forEach((session, index) => {
+      const role = session.kind === "branch" ? "branch" : "main";
+      const branchInfo = session.parentSessionId
+        ? ` <- ${session.parentSessionId.slice(0, 8)}`
+        : "";
+      console.log(
+        `${index + 1}. ${session.title} | ${role} | ${session.provider || "(未知 provider)"} | ${session.sessionId}${branchInfo}`,
+      );
+    });
+  }
+  await pause(rl);
+}
+
+async function captureTitle(rl, providerName, kind) {
+  clearScreen();
+  console.log("会话标题");
+  console.log("========");
+  const input = (await askText(
+    rl,
+    `输入标题（留空自动生成：${defaultTitle(providerName, kind)}）: `,
+  )).trim();
+  return input || defaultTitle(providerName, kind);
+}
+
+async function launchNewSession(rl, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  const projectState = loadProject(cwd);
+  const providersState = loadProviders();
+  if (!providersState.providers.length) {
+    clearScreen();
+    console.log("先去配一个 provider/key 再开。");
+    await pause(rl);
+    return;
+  }
+  let provider = providersState.providers.find(
+    (item) => item.name === (projectState.provider || projectState.defaultProvider),
+  );
+  if (!provider) {
+    provider =
+      (await chooseProviderMenu(rl, projectState, providersState)) ||
+      providersState.providers.find((item) => item.name === providersState.default) ||
+      providersState.providers[0];
+  }
+  if (!provider) return;
+
+  projectState.provider = provider.name;
+  projectState.defaultProvider = provider.name;
+  saveProject(projectState, cwd);
+  const title = await captureTitle(rl, provider.name, "main");
+
+  clearScreen();
+  console.log(`准备启动新主线会话 · provider=${provider.name}`);
+  await pause(rl, "按回车进入 Codex...");
+
+  setRawMode(false);
+  const startedAtMs = Date.now();
+  await runCodex([], buildCodexEnv(provider), projectState.root);
+  setRawMode(true);
+
+  const linkedSessionId = await maybeLinkLatestSession(
+    projectState.root,
+    provider.name,
+    startedAtMs,
+  );
+  if (linkedSessionId) {
+    projectState.lastSessionId = linkedSessionId;
+    projectState.mainSessionId = linkedSessionId;
+    saveProject(projectState, cwd);
+    upsertSessionMeta(
+      {
+        sessionId: linkedSessionId,
+        title,
+        kind: "main",
+        parentSessionId: null,
+        provider: provider.name,
+        isMain: true,
+        createdAt: nowIso(),
+        updatedAt: nowIso(),
+      },
+      cwd,
+    );
+  }
+}
+
+async function resumeLatestSession(rl, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  const sessions = listProjectSessionsWithMeta(cwd);
+  if (!sessions.length) {
+    clearScreen();
+    console.log("本项目还没有可恢复的会话，先开新的。");
+    await pause(rl);
+    return;
+  }
+  return resumeSpecificSession(rl, sessions[0].sessionId, cwd);
+}
+
+async function resumeMainSession(rl, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  const projectState = loadProject(cwd);
+  const main = getCurrentMainSession(projectState, cwd);
+  if (!main) {
+    clearScreen();
+    console.log("当前项目没有主线会话。");
+    await pause(rl);
+    return;
+  }
+  return resumeSpecificSession(rl, main.sessionId, cwd);
+}
+
+async function resumeSpecificSession(rl, sessionId, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  const projectState = loadProject(cwd);
+  const providersState = loadProviders();
+  const linkedProviderName =
+    projectState.provider ||
+    projectState.defaultProvider ||
+    getProviderForSession(sessionId, cwd) ||
+    providersState.default;
+  const provider = providersState.providers.find(
+    (item) => item.name === linkedProviderName,
+  );
+  if (!provider) {
+    clearScreen();
+    console.log("找不到对应 provider。先去 provider 管理里配好。");
+    await pause(rl);
+    return;
+  }
+
+  projectState.provider = provider.name;
+  projectState.lastSessionId = sessionId;
+  saveProject(projectState, cwd);
+  upsertSessionMeta(
+    {
+      sessionId,
+      provider: provider.name,
+      updatedAt: nowIso(),
+    },
+    cwd,
+  );
+
+  clearScreen();
+  console.log(`准备恢复会话 ${sessionId}`);
+  console.log(`provider=${provider.name}`);
+  await pause(rl, "按回车进入 Codex...");
+
+  setRawMode(false);
+  await runCodex(["resume", sessionId], buildCodexEnv(provider), projectState.root);
+  setRawMode(true);
+}
+
+async function pickSessionAndResume(rl, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  const sessions = listProjectSessionsWithMeta(cwd);
+  if (!sessions.length) {
+    clearScreen();
+    console.log("本项目还没有可恢复的会话。");
+    await pause(rl);
+    return;
+  }
+  const idx = await selectIndex(
+    "选择历史会话",
+    sessions.slice(0, 30).map((session) => {
+      return `${session.title} | ${session.provider || "未知 provider"} | ${session.kind} | ${session.sessionId}`;
+    }),
+    "↑↓/数字 选择 · Enter 恢复 · Esc 返回",
+  );
+  if (idx === null) return;
+  await resumeSpecificSession(rl, sessions[idx].sessionId, cwd);
+}
+
+async function chooseMainSessionMenu(rl, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  const projectState = loadProject(cwd);
+  const mains = getMainSessions(cwd);
+  if (!mains.length) {
+    clearScreen();
+    console.log("当前项目还没有主线会话。先开一个新的。");
+    await pause(rl);
+    return null;
+  }
+  const idx = await selectIndex(
+    "主线列表",
+    mains.map((session) => {
+      const marker =
+        session.sessionId === projectState.mainSessionId ? " (当前主线)" : "";
+      return `${formatSessionLabel(session, cwd)}${marker}`;
+    }),
+    "↑↓/数字 选择 · Enter 进入 · Esc 返回",
+  );
+  if (idx === null) return null;
+  return mains[idx];
+}
+
+async function navigateSessionTree(rl, rootSessionId, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  let currentId = rootSessionId;
+  while (currentId) {
+    const allSessions = listProjectSessionsWithMeta(cwd);
+    const current = allSessions.find((item) => item.sessionId === currentId);
+    if (!current) {
+      clearScreen();
+      console.log("当前会话不存在了，可能已经被删除。");
+      await pause(rl);
+      return;
+    }
+
+    const children = getChildSessions(current.sessionId, cwd);
+    const actions = [
+      `恢复当前会话`,
+      `从当前会话分叉`,
+      ...(children.length ? ["进入子分支"] : []),
+      ...(current.parentSessionId ? ["返回父会话"] : []),
+      `返回主线列表`,
+      `删除当前会话（硬删除）`,
+    ];
+
+    const idx = await selectIndexWithContext(
+      `会话树 · ${current.title}`,
+      [
+        `会话ID: ${current.sessionId}`,
+        `类型: ${current.kind}`,
+        `会话 Provider: ${current.provider || "未知 provider"}`,
+        `项目当前 Provider: ${loadProject(cwd).provider || loadProject(cwd).defaultProvider || "未设置"}`,
+        `子分支数: ${children.length}`,
+      ],
+      actions,
+      "↑↓/数字 选择 · Enter 确认 · Esc 返回",
+    );
+    if (idx === null) return;
+    const action = actions[idx];
+    if (action === "恢复当前会话") {
+      await resumeSpecificSession(rl, current.sessionId, cwd);
+      return;
+    }
+    if (action === "从当前会话分叉") {
+      await forkFromSession(rl, current, cwd);
+      return;
+    }
+    if (action === "进入子分支") {
+      const childIdx = await selectIndex(
+        `子分支 · ${current.title}`,
+        children.map((session) => formatSessionLabel(session, cwd)),
+        "↑↓/数字 选择 · Enter 进入 · Esc 返回",
+      );
+      if (childIdx === null) continue;
+      currentId = children[childIdx].sessionId;
+      continue;
+    }
+    if (action === "返回父会话") {
+      currentId = current.parentSessionId;
+      continue;
+    }
+    if (action === "删除当前会话（硬删除）") {
+      const result = await deleteSpecificSession(rl, current, cwd);
+      if (!result || result.deleted === false) {
+        continue;
+      }
+      if (result.nextSessionId) {
+        currentId = result.nextSessionId;
+        continue;
+      }
+      if (result.backToMainList) {
+        return;
+      }
+      continue;
+    }
+    if (action === "返回主线列表") {
+      return;
+    }
+  }
+}
+
+async function forkFromSession(rl, source, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  const projectState = loadProject(cwd);
+  const providersState = loadProviders();
+  const provider =
+    providersState.providers.find((item) => item.name === projectState.provider) ||
+    providersState.providers.find((item) => item.name === projectState.defaultProvider) ||
+    providersState.providers.find((item) => item.name === source.provider) ||
+    providersState.providers[0];
+  if (!provider) {
+    clearScreen();
+    console.log("找不到可用 provider。");
+    await pause(rl);
+    return;
+  }
+  const title = await captureTitle(rl, provider.name, "branch");
+  clearScreen();
+  console.log(`准备从 ${source.title} 分叉`);
+  console.log(`provider=${provider.name}`);
+  await pause(rl, "按回车进入 Codex...");
+
+  setRawMode(false);
+  const startedAtMs = Date.now();
+  await runCodex(["fork", source.sessionId], buildCodexEnv(provider), projectState.root);
+  setRawMode(true);
+
+  const linkedSessionId = await maybeLinkLatestSession(
+    projectState.root,
+    provider.name,
+    startedAtMs,
+  );
+  if (linkedSessionId) {
+    projectState.provider = provider.name;
+    projectState.defaultProvider = provider.name;
+    projectState.lastSessionId = linkedSessionId;
+    saveProject(projectState, cwd);
+    upsertSessionMeta(
+      {
+        sessionId: linkedSessionId,
+        title,
+        kind: "branch",
+        parentSessionId: source.sessionId,
+        provider: provider.name,
+        isMain: false,
+        createdAt: nowIso(),
+        updatedAt: nowIso(),
+      },
+      cwd,
+    );
+  }
+}
+
+async function deleteSpecificSession(rl, target, cwd = process.cwd()) {
+  hydrateProjectMetadata(cwd);
+  const projectState = loadProject(cwd);
+  const fallbackParentSessionId = target.parentSessionId || null;
+  const childCount = countChildBranches(target.sessionId, cwd);
+  clearScreen();
+  console.log("硬删除确认");
+  console.log("============");
+  console.log("标题:", target.title);
+  console.log("会话:", target.sessionId);
+  console.log("类型:", target.kind);
+  console.log("下游分支数:", childCount);
+  console.log("注意：这里只删除当前会话本身，不自动删它的分支。");
+  const confirm = (await askText(rl, "输入 yes / y 确认删除: ")).trim().toLowerCase();
+  if (!["yes", "y"].includes(confirm)) {
+    clearScreen();
+    console.log("已取消删除。");
+    await pause(rl);
+    return {
+      deleted: false,
+      nextSessionId: target.sessionId,
+      backToMainList: false,
+    };
+  }
+
+  setRawMode(false);
+  const exitCode = await runCodex(
+    ["delete", "--force", target.sessionId],
+    {},
+    projectState.root,
+  );
+  setRawMode(true);
+
+  const stillExists = hasOfficialSession(target.sessionId, projectState.root);
+  if (exitCode !== 0 || stillExists) {
+    clearScreen();
+    console.log("删除失败");
+    console.log("========");
+    console.log("Codex 没有成功删除这个会话。");
+    console.log(`退出码: ${exitCode}`);
+    console.log(`会话仍存在: ${stillExists ? "是" : "否"}`);
+    await pause(rl, "按回车返回当前会话...");
+    return {
+      deleted: false,
+      nextSessionId: target.sessionId,
+      backToMainList: false,
+    };
+  }
+
+  removeSessionMeta(target.sessionId, cwd);
+  if (projectState.lastSessionId === target.sessionId) projectState.lastSessionId = null;
+  if (projectState.mainSessionId === target.sessionId) projectState.mainSessionId = null;
+  saveProject(projectState, cwd);
+  clearScreen();
+  console.log("已硬删除会话:", target.sessionId);
+  await pause(rl);
+  return {
+    deleted: true,
+    nextSessionId: fallbackParentSessionId,
+    backToMainList: !fallbackParentSessionId,
+  };
+}
+
+async function interactive(cwd = process.cwd()) {
+  ensureDir(CONFIG_ROOT);
+  const projectCheck = ensureUsableProject(cwd);
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  readline.emitKeypressEvents(process.stdin, rl);
+  setRawMode(true);
+
+  try {
+    if (!projectCheck.ok) {
+      clearScreen();
+      console.log("项目检查未通过");
+      console.log("==============");
+      console.log(projectCheck.reason);
+      await pause(rl);
+      return;
+    }
+    hydrateProjectMetadata(cwd);
+    while (true) {
+      const projectState = loadProject(cwd);
+      const action = await selectIndex(
+        `Codexx · ${projectState.name}`,
+        [
+          "新主线会话",
+          "选择主线",
+          "恢复最近会话",
+          "Provider 管理",
+          "查看当前状态",
+          "退出",
+        ],
+        "↑↓/数字 选择 · Enter 确认 · Esc 退出",
+      );
+
+      if (action === null || action === 5) return;
+      if (action === 0) await launchNewSession(rl, cwd);
+      else if (action === 1) {
+        const selectedMain = await chooseMainSessionMenu(rl, cwd);
+        if (selectedMain) await navigateSessionTree(rl, selectedMain.sessionId, cwd);
+      } else if (action === 2) await resumeLatestSession(rl, cwd);
+      else if (action === 3) await providerManagementMenu(rl, cwd);
+      else if (action === 4) await showCurrentStatus(rl, cwd);
+    }
+  } finally {
+    setRawMode(false);
+    rl.close();
+  }
+}
+
+function printHelp() {
+  console.log(`codexx
+
+用法:
+  codexx               进入交互菜单
+  codexx init          初始化当前项目状态
+  codexx list          列出当前项目会话
+  codexx providers     查看 provider 列表
+`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const projectCheck = ensureUsableProject(process.cwd());
+  if (argv.includes("--help") || argv.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  const cmd = argv[0];
+  if (!cmd) {
+    if (!projectCheck.ok) {
+      console.error(projectCheck.reason);
+      process.exit(1);
+    }
+    await interactive();
+    return;
+  }
+
+  if (cmd === "init") {
+    if (!projectCheck.ok) {
+      console.error(projectCheck.reason);
+      process.exit(1);
+    }
+    const state = loadProject();
+    saveProject(state);
+    console.log("项目已初始化:", getProjectPaths().projectFile);
+    return;
+  }
+
+  if (cmd === "providers") {
+    console.log(JSON.stringify(loadProviders(), null, 2));
+    return;
+  }
+
+  if (cmd === "list") {
+    if (!projectCheck.ok) {
+      console.error(projectCheck.reason);
+      process.exit(1);
+    }
+    hydrateProjectMetadata();
+    const sessions = listProjectSessionsWithMeta();
+    if (!sessions.length) {
+      console.log("(空)");
+      return;
+    }
+    sessions.forEach((session) => {
+      console.log(
+        `${session.sessionId}  ${session.provider || "未知 provider"}  ${session.kind}  ${session.title}`,
+      );
+    });
+    return;
+  }
+
+  printHelp();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});