Merge branch 'implement-fork-command'

Author: qorzj

README-en.md

@@ -75,6 +75,7 @@ Skills are discovered from these locations, in priority order:
 | `/`              | Open the skills / commands menu                         |
 | `/new`           | Start a fresh conversation                              |
 | `/resume`        | Choose a previous conversation to continue              |
+| `/fork`          | Fork the current conversation     |
 | `/continue`      | Continue the active conversation or pick one to resume  |
 | `/model`         | Switch model, thinking mode, and reasoning effort       |
 | `/raw`           | Toggle display mode (Normal / Lite / Raw scrollback)    |

README-zh_CN.md

@@ -74,6 +74,7 @@ Skills 会按以下优先级扫描：
 | `/`         | 打开 skills / 命令菜单                 |
 | `/new`      | 开始新对话                            |
 | `/resume`   | 选择历史对话继续                         |
+| `/fork`     | 从当前对话创建独立的新会话                    |
 | `/continue` | 继续当前对话，或选择历史对话恢复                 |
 | `/model`    | 切换模型、思考模式和推理强度                   |
 | `/raw`      | 切换显示模式（Normal / Lite / Raw 滚动回溯） |

README.md

@@ -74,6 +74,7 @@ Skills 会按以下优先级扫描：
 | `/`         | 打开 skills / 命令菜单                 |
 | `/new`      | 开始新对话                            |
 | `/resume`   | 选择历史对话继续                         |
+| `/fork`     | 从当前对话创建独立的新会话                    |
 | `/continue` | 继续当前对话，或选择历史对话恢复                 |
 | `/model`    | 切换模型、思考模式和推理强度                   |
 | `/raw`      | 切换显示模式（Normal / Lite / Raw 滚动回溯） |

docs/quickstart.md

@@ -120,6 +120,7 @@ deepcode -p "总结这个项目"
 | ---- | ---- |
 | `/new` | 开始新对话 |
 | `/resume` | 选择历史对话继续 |
+| `/fork` | 从当前对话创建独立的新会话 |
 | `/continue` | 继续当前对话，或恢复最近的对话 |
 | `/model` | 切换模型、思考模式和推理强度 |
 | `/init` | 为当前项目生成 `AGENTS.md` 指令文件 |

docs/quickstart_en.md

@@ -120,6 +120,7 @@ Type `/` in the input box to open the command menu.
 | ------- | ------ |
 | `/new` | Start a new conversation |
 | `/resume` | Choose a previous conversation to continue |
+| `/fork` | Fork the current conversation |
 | `/continue` | Continue the current conversation or resume the latest one |
 | `/model` | Switch model, thinking mode, and reasoning effort |
 | `/init` | Create an `AGENTS.md` instruction file for the current project |

docs/session-persistence.md

@@ -1,6 +1,6 @@
 # 会话持久化机制
 
-Deep Code 会把每个项目的会话记录保存在本机用户目录中。会话历史用于 `/resume`、`/continue` 和 `/undo`，不依赖当前终端进程是否仍在运行。
+Deep Code 会把每个项目的会话记录保存在本机用户目录中。会话历史用于 `/resume`、`/fork`、`/continue` 和 `/undo`，不依赖当前终端进程是否仍在运行。
 
 ## 存储位置
 
@@ -31,6 +31,7 @@ Deep Code 会把每个项目的会话记录保存在本机用户目录中。会
 - 最近一次 assistant 回复、思考内容、拒绝原因和失败原因。
 - 最近一次工具调用信息、token 用量和活跃 token 数。
 - 当前会话中仍被跟踪的子进程信息。
+- fork 会话的直接来源 `sessionId` 和源会话最后一条消息的 `messageId`。
 
 会话标题默认来自首次用户输入的前 100 个字符。使用会话列表中的重命名功能会更新索引里的标题。
 
@@ -86,6 +87,12 @@ Deep Code 使用 `file-history/.git` 保存代码快照。这个仓库只作为
 
 继续会话时，Deep Code 会读取会话消息文件，过滤已压缩的旧消息，修复未完成的工具调用上下文，并把可用历史转换为模型请求消息。
 
+### Fork 会话
+
+`/fork` 会复制当前活动会话并切换到新会话。命令行中的 `--fork <session-id>` 会复制指定会话；单独使用 `-f` 或 `--fork` 时，会复制当前项目最近更新的会话。`--fork` 不能与 `--resume` 或 `--last` 同时使用。
+
+新会话保留消息历史、当前上下文 token 数和代码快照分支起点，但累计 `usage` 和按模型统计的 usage 会清零。之后新增的消息、模型用量和代码快照只更新 fork 出来的会话，不会修改源会话。
+
 ### 长会话压缩
 
 当会话上下文过长时，Deep Code 会触发压缩流程：

docs/session-persistence_en.md

@@ -1,6 +1,6 @@
 # Session Persistence
 
-Deep Code stores per-project session history in the local user directory. This history powers `/resume`, `/continue`, and `/undo`, and it remains available after the current terminal process exits.
+Deep Code stores per-project session history in the local user directory. This history powers `/resume`, `/fork`, `/continue`, and `/undo`, and it remains available after the current terminal process exits.
 
 ## Storage Location
 
@@ -31,6 +31,7 @@ The project storage directory contains these main files and directories:
 - Latest assistant reply, thinking content, refusal reason, and failure reason.
 - Latest tool-call data, token usage, and active token count.
 - Metadata for subprocesses still tracked by the session.
+- The direct source session ID and source head message ID for forked sessions.
 
 The default session title comes from the first 100 characters of the first user prompt. Renaming a session from the session list updates the title in the index.
 
@@ -86,6 +87,12 @@ The per-project session list keeps the 50 most recent entries. When the limit is
 
 When continuing a session, Deep Code reads the message file, filters compacted old messages, repairs incomplete tool-call context, and converts the usable history into model request messages.
 
+### Forking A Session
+
+`/fork` copies the active conversation and switches to the new session. On the command line, `--fork <session-id>` copies a specific session; bare `-f` or `--fork` copies the most recently updated session in the current project. `--fork` cannot be combined with `--resume` or `--last`.
+
+The new session keeps the message history, current context token count, and code-checkpoint starting point, while cumulative `usage` and per-model usage are reset. Subsequent messages, model usage, and checkpoints update only the forked session and leave the source session unchanged.
+
 ### Long-Session Compaction
 
 When the conversation context grows too large, Deep Code can compact earlier messages:

packages/cli/src/cli-args.ts

@@ -31,6 +31,8 @@ export interface ParsedCliArgs {
    *   - `string`     — --resume <sessionId> was used
    */
   resume: string | true | undefined;
+  /** Fork source session. Bare --fork selects the most recent project session. */
+  fork: string | true | undefined;
   /** True when --version / -v was passed */
   version: boolean;
   /** True when --help / -h was passed */
@@ -65,6 +67,7 @@ const EPILOG = [
   "  /new             Start a fresh conversation",
   "  /init            Initialize an AGENTS.md file with instructions for LLM",
   "  /resume          Pick a previous conversation to continue",
+  "  /fork            Fork the current conversation",
   "  /continue        Continue the active conversation, or resume one if empty",
   "  /undo            Restore code and/or conversation to a previous point",
   "  /mcp             Show MCP server status and available tools",
@@ -97,6 +100,11 @@ async function configureYargs(argv?: string[]) {
           type: "string",
           describe: "Resume a specific session by its ID. Use without an ID to show session picker.",
         })
+        .option("fork", {
+          alias: "f",
+          type: "string",
+          describe: "Fork a specific session by its ID. Use without an ID to fork the most recent session.",
+        })
         .option("last", {
           alias: "l",
           type: "boolean",
@@ -120,10 +128,19 @@ async function configureYargs(argv?: string[]) {
           if (argv["last"] === true && argv["resume"] !== undefined) {
             return "Cannot use --last together with --resume. Use --last to resume the most recent session, or --resume <sessionId> for a specific session.";
           }
+          if (argv["fork"] !== undefined && argv["resume"] !== undefined) {
+            return "Cannot use --fork together with --resume.";
+          }
+          if (argv["last"] === true && argv["fork"] !== undefined) {
+            return "Cannot use --last together with --fork.";
+          }
           // validate --resume <sessionId> format if provided
           if (argv["resume"] && argv["resume"] !== "" && !isValidSessionId(argv["resume"] as string)) {
             return `Invalid session ID: "${argv["resume"]}". Must be a valid UUID (e.g., "123e4567-e89b-12d3-a456-426614174000").`;
           }
+          if (argv["fork"] && argv["fork"] !== "" && !isValidSessionId(argv["fork"] as string)) {
+            return `Invalid session ID: "${argv["fork"]}". Must be a valid UUID (e.g., "123e4567-e89b-12d3-a456-426614174000").`;
+          }
           // empty prompt is meaningless
           if (prompt !== undefined && prompt.trim() === "") {
             return "--prompt / -p requires a non-empty value.";
@@ -141,6 +158,7 @@ async function configureYargs(argv?: string[]) {
     .example("deepcode -p <prompt>", "Launch the TUI and submit a prompt")
     .example("deepcode -x -p <prompt>", "Run one prompt without launching the TUI")
     .example("deepcode -r, --resume [sessionId]", "Resume a session or show session picker")
+    .example("deepcode -f, --fork [sessionId]", "Fork a session or the most recent session")
     .example('cat error.log | deepcode -x -p "Explain this error"', "Use piped stdin as additional context")
     .epilog(EPILOG)
     .strict()
@@ -181,10 +199,21 @@ export async function parseArguments(argv?: string[]): Promise<ParsedCliArgs> {
     resume = resumeRaw;
   }
 
+  const forkRaw = parsed.fork as string | undefined;
+  let fork: ParsedCliArgs["fork"];
+  if (forkRaw === undefined) {
+    fork = undefined;
+  } else if (forkRaw === "") {
+    fork = true;
+  } else {
+    fork = forkRaw;
+  }
+
   return {
     prompt: parsed.prompt as string | undefined,
     exec: parsed.exec === true,
     resume,
+    fork,
     version: parsed.version === true,
     help: parsed.help === true,
     last: parsed.last === true,

packages/cli/src/cli.tsx

@@ -30,6 +30,7 @@ async function main(): Promise<void> {
 
   let initialPrompt = parsed.prompt;
   let resumeSessionId = parsed.resume;
+  let forkSessionId = parsed.fork;
   const projectRoot = process.cwd();
 
   // Resolve --last to the most recent session ID for the current project
@@ -51,11 +52,30 @@ async function main(): Promise<void> {
     }
   }
 
+  if (forkSessionId === true) {
+    const projectCode = getProjectCode(projectRoot);
+    const indexPath = join(homedir(), ".deepcode", "projects", projectCode, "sessions-index.json");
+    try {
+      const index = JSON.parse(readFileSync(indexPath, "utf-8"));
+      const entries: { id: string; updateTime: string }[] = Array.isArray(index?.entries) ? index.entries : [];
+      if (entries.length === 0) {
+        writeStderrLine("No previous sessions found for the current project.\n");
+        process.exit(1);
+      }
+      const mostRecent = entries.reduce((a, b) => (a.updateTime > b.updateTime ? a : b));
+      forkSessionId = mostRecent.id;
+    } catch {
+      writeStderrLine("No previous sessions found for the current project.\n");
+      process.exit(1);
+    }
+  }
+
   if (parsed.exec) {
     process.exitCode = await runExecMode({
       prompt: parsed.prompt!,
       projectRoot,
-      resumeSessionId: typeof parsed.resume === "string" ? parsed.resume : undefined,
+      resumeSessionId: typeof resumeSessionId === "string" ? resumeSessionId : undefined,
+      forkSessionId: typeof forkSessionId === "string" ? forkSessionId : undefined,
     });
     return;
   }
@@ -83,6 +103,22 @@ async function main(): Promise<void> {
     }
   }
 
+  if (typeof forkSessionId === "string") {
+    const projectCode = getProjectCode(projectRoot);
+    const indexPath = join(homedir(), ".deepcode", "projects", projectCode, "sessions-index.json");
+    try {
+      const index = JSON.parse(readFileSync(indexPath, "utf-8"));
+      const found = Array.isArray(index?.entries) && index.entries.some((e: { id: string }) => e.id === forkSessionId);
+      if (!found) {
+        writeStderrLine(`No saved session found with ID "${forkSessionId}".\n`);
+        process.exit(1);
+      }
+    } catch {
+      writeStderrLine(`No saved session found with ID "${forkSessionId}".\n`);
+      process.exit(1);
+    }
+  }
+
   const updatePromptResult = await promptForPendingUpdate(packageInfo);
   if (updatePromptResult.installed) {
     process.exit(0);
@@ -96,12 +132,15 @@ async function main(): Promise<void> {
     initialPrompt = undefined;
     const appResumeSessionId = resumeSessionId;
     resumeSessionId = undefined;
+    const appForkSessionId = forkSessionId;
+    forkSessionId = undefined;
     const inkInstance = render(
       <AppContainer
         projectRoot={projectRoot}
         version={packageInfo?.version ?? CLI_VERSION}
         initialPrompt={appInitialPrompt}
         resumeSessionId={appResumeSessionId}
+        forkSessionId={typeof appForkSessionId === "string" ? appForkSessionId : undefined}
         onRestart={() => restartRef.current?.()}
       />,
       { exitOnCtrlC: false }

packages/cli/src/exec-runner.ts

@@ -15,6 +15,7 @@ type ExecSessionManager = Pick<
   | "dispose"
   | "getActiveSessionId"
   | "getSession"
+  | "forkSession"
   | "handleUserPrompt"
   | "initMcpServers"
   | "interruptActiveSession"
@@ -30,6 +31,7 @@ export interface ExecRunnerOptions {
   prompt: string;
   projectRoot: string;
   resumeSessionId?: string;
+  forkSessionId?: string;
   input?: ExecInputStream;
 }
 
@@ -88,13 +90,21 @@ export async function runExecMode(
         return 1;
       }
     }
+    if (options.forkSessionId) {
+      if (!manager.getSession(options.forkSessionId)) {
+        deps.writeStderrLine(`No saved session found with ID "${options.forkSessionId}".`);
+        return 1;
+      }
+    }
 
     const prompt = await deps.buildPrompt(options.prompt, options.input ?? process.stdin);
     if (interrupted) {
       return 130;
     }
 
-    if (options.resumeSessionId) {
+    if (options.forkSessionId) {
+      manager.setActiveSessionId(manager.forkSession(options.forkSessionId));
+    } else if (options.resumeSessionId) {
       manager.setActiveSessionId(options.resumeSessionId);
     }