feat(kimi-code): add -w, --worktree [name] flag for isolated sessions

.changeset/add-worktree-flag.md

@@ -0,0 +1,6 @@
+---
+"@moonshot-ai/agent-core": minor
+"@moonshot-ai/kimi-code": minor
+---
+
+Add `-w, --worktree [name]` flag to create a new git worktree for the session, and surface the worktree metadata in the agent system prompt.

apps/kimi-code/src/cli/commands.ts

@@ -74,7 +74,13 @@ export function createProgram(
     )
     .addOption(new Option('--yes').hideHelp().default(false))
     .addOption(new Option('--auto-approve').hideHelp().default(false))
-    .option('--plan', 'Start in plan mode.', false);
+    .option('--plan', 'Start in plan mode.', false)
+    .addOption(
+      new Option(
+        '-w, --worktree [name]',
+        'Create a new git worktree for this session (optionally specify a name).',
+      ).argParser((val: string | boolean) => (val === true ? '' : (val as string))),
+    );
 
   registerExportCommand(program);
   registerProviderCommand(program);
@@ -111,6 +117,9 @@ export function createProgram(
     const yoloValue = raw['yolo'] === true || raw['yes'] === true || raw['autoApprove'] === true;
     const autoValue = raw['auto'] === true;
 
+    const rawWorktree = raw['worktree'];
+    const worktreeValue = rawWorktree === true ? '' : (rawWorktree as string | undefined);
+
     const opts: CLIOptions = {
       session: sessionValue,
       continue: raw['continue'] as boolean,
@@ -121,6 +130,7 @@ export function createProgram(
       outputFormat: raw['outputFormat'] as CLIOptions['outputFormat'],
       prompt: raw['prompt'] as string | undefined,
       skillsDirs: raw['skillsDir'] as string[],
+      worktree: worktreeValue,
     };
 
     onMain(opts);

apps/kimi-code/src/cli/options.ts

@@ -11,6 +11,11 @@ export interface CLIOptions {
   outputFormat: PromptOutputFormat | undefined;
   prompt: string | undefined;
   skillsDirs: string[];
+  worktree?: string;
+  /** Populated during startup when --worktree is used. */
+  worktreePath?: string;
+  /** Populated during startup when --worktree is used. */
+  parentRepoPath?: string;
 }
 
 export interface ValidatedOptions {
@@ -55,5 +60,11 @@ export function validateOptions(opts: CLIOptions): ValidatedOptions {
   if (opts.yolo && opts.auto) {
     throw new OptionConflictError('Cannot combine --yolo with --auto.');
   }
+  if (opts.worktree !== undefined && opts.session !== undefined) {
+    throw new OptionConflictError('Cannot combine --worktree with --session.');
+  }
+  if (opts.worktree !== undefined && opts.continue) {
+    throw new OptionConflictError('Cannot combine --worktree with --continue.');
+  }
   return { options: opts, uiMode: promptMode ? 'print' : 'shell' };
 }

apps/kimi-code/src/cli/run-prompt.ts

@@ -156,7 +156,7 @@ export async function runPrompt(
     } else {
       await runPromptTurn(session, opts.prompt!, outputFormat, stdout, stderr);
     }
-    writeResumeHint(session.id, outputFormat, stdout, stderr);
+    writeResumeHint(session.id, outputFormat, stdout, stderr, opts.worktreePath !== undefined ? workDir : undefined);
 
     withTelemetryContext({ sessionId: session.id }).track('exit', {
       duration_s: (Date.now() - startedAt) / 1000,
@@ -290,7 +290,16 @@ async function resolvePromptSession(
   }
 
   const model = requireConfiguredModel(opts.model, defaultModel);
-  const session = await harness.createSession({ workDir, model, permission: 'auto' });
+  const metadata =
+    opts.worktreePath !== undefined && opts.parentRepoPath !== undefined
+      ? { worktreePath: opts.worktreePath, parentRepoPath: opts.parentRepoPath }
+      : undefined;
+  // Note: --prompt mode intentionally does not auto-remove the worktree on
+  // exit. Unlike the TUI, a prompt session always produces at least a user
+  // prompt and assistant response, so the "empty session" cleanup rule does
+  // not apply; leaving the worktree makes the non-interactive output
+  // inspectable after the fact.
+  const session = await harness.createSession({ workDir, model, permission: 'auto', metadata });
   installHeadlessHandlers(session);
   return {
     session,
@@ -589,8 +598,10 @@ function writeResumeHint(
   outputFormat: PromptOutputFormat,
   stdout: PromptOutput,
   stderr: PromptOutput,
+  workDir?: string,
 ): void {
-  const command = `kimi -r ${sessionId}`;
+  const command =
+    workDir !== undefined ? `cd "${workDir}" && kimi -r ${sessionId}` : `kimi -r ${sessionId}`;
   const content = `To resume this session: ${command}`;
   if (outputFormat === 'stream-json') {
     const message: PromptJsonResumeMetaMessage = {

apps/kimi-code/src/cli/run-shell.ts

@@ -2,6 +2,8 @@ import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+import { removeWorktree } from '#/utils/git/worktree';
+
 import {
   setCrashPhase,
   setTelemetryContext,
@@ -133,14 +135,31 @@ export async function runShell(
 
   tui.onExit = async (exitCode = 0) => {
     const sessionId = tui.getCurrentSessionId();
-    const hasContent = tui.hasSessionContent();
+    const hasContent = tui.hasEverHadSessionContent();
     setCrashPhase('shutdown');
     trackLifecycle('exit', { duration_s: (Date.now() - startedAt) / 1000 });
+
+    // Clean up the git worktree for empty sessions so abandoned worktrees
+    // do not accumulate. Use the lifetime flag so `/new` does not delete a
+    // worktree that held an earlier session.
+    if (!hasContent && opts.worktreePath !== undefined && opts.parentRepoPath !== undefined) {
+      try {
+        removeWorktree(opts.parentRepoPath, opts.worktreePath);
+      } catch (cleanupError) {
+        // Best-effort cleanup only; do not let cleanup failures prevent a clean exit.
+        log.warn('Failed to clean up git worktree on exit', cleanupError);
+      }
+    }
+
     await shutdownTelemetry({ timeoutMs: CLI_SHUTDOWN_TIMEOUT_MS });
     const gutter = ' '.repeat(CHROME_GUTTER);
     process.stdout.write(`${gutter}Bye!\n`);
     if (sessionId !== '' && hasContent) {
-      process.stderr.write(`\n${gutter}To resume this session: kimi -r ${sessionId}\n`);
+      const resumeCommand =
+        opts.worktreePath !== undefined
+          ? `cd "${process.cwd()}" && kimi -r ${sessionId}`
+          : `kimi -r ${sessionId}`;
+      process.stderr.write(`\n${gutter}To resume this session: ${resumeCommand}\n`);
     }
     process.exit(exitCode);
   };

apps/kimi-code/src/main.ts

@@ -27,6 +27,8 @@ import type { CLIOptions } from './cli/options';
 import { OptionConflictError, validateOptions } from './cli/options';
 import { runPrompt } from './cli/run-prompt';
 import { runShell } from './cli/run-shell';
+import { relative, resolve } from 'node:path';
+import { createWorktree, findGitRoot, removeWorktree, WorktreeError } from './utils/git/worktree';
 import { formatStartupError } from './cli/startup-error';
 import { runPluginNodeEntry } from './cli/sub/plugin-run-node';
 import { handleUpgrade } from './cli/sub/upgrade';
@@ -38,6 +40,22 @@ import { cleanupStaleNativeCacheForCurrent } from './native/native-assets';
 import { installNativeModuleHook } from './native/module-hook';
 import { runNativeAssetSmokeIfRequested } from './native/smoke';
 
+function prepareWorktree(worktreeName: string): { worktreePath: string; parentRepoPath: string } {
+  const cwd = process.cwd();
+  const repoRoot = findGitRoot(cwd);
+  if (repoRoot === null) {
+    throw new WorktreeError('--worktree requires the working directory to be inside a git repository.');
+  }
+  const worktreePath = createWorktree(repoRoot, worktreeName || undefined);
+  const relativeCwd = relative(repoRoot, cwd);
+  const targetCwd =
+    relativeCwd.length > 0 && relativeCwd !== '.'
+      ? resolve(worktreePath, relativeCwd)
+      : worktreePath;
+  process.chdir(targetCwd);
+  return { worktreePath, parentRepoPath: repoRoot };
+}
+
 export async function handleMainCommand(opts: CLIOptions, version: string): Promise<void> {
   let validated: ReturnType<typeof validateOptions>;
   try {
@@ -58,12 +76,46 @@ export async function handleMainCommand(opts: CLIOptions, version: string): Prom
     process.exit(0);
   }
 
-  if (validated.uiMode === 'print') {
-    await runPrompt(validated.options, version);
-    return;
+  if (opts.worktree !== undefined) {
+    try {
+      const { worktreePath, parentRepoPath } = await prepareWorktree(opts.worktree);
+      opts.worktreePath = worktreePath;
+      opts.parentRepoPath = parentRepoPath;
+    } catch (error) {
+      if (error instanceof WorktreeError) {
+        process.stderr.write(`error: ${error.message}\n`);
+        process.exit(1);
+      }
+      throw error;
+    }
   }
 
-  await runShell(validated.options, version);
+  try {
+    if (validated.uiMode === 'print') {
+      await runPrompt(validated.options, version);
+      return;
+    }
+
+    await runShell(validated.options, version);
+  } catch (error) {
+    // If the shell runner failed during startup after we created a worktree,
+    // the worktree is still empty (no session ran), so clean it up to avoid
+    // leaks. Print mode intentionally leaves the worktree inspectable even on
+    // failure, so we do not clean it up here.
+    if (
+      validated.uiMode !== 'print' &&
+      opts.worktreePath !== undefined &&
+      opts.parentRepoPath !== undefined
+    ) {
+      try {
+        removeWorktree(opts.parentRepoPath, opts.worktreePath);
+      } catch (cleanupError) {
+        // Best-effort cleanup only; do not let cleanup failures mask the original error.
+        log.warn('Failed to clean up git worktree after runner startup failed', cleanupError);
+      }
+    }
+    throw error;
+  }
 }
 
 /** `kimi migrate`: launch the migration screen only, then exit. */

apps/kimi-code/src/tui/kimi-tui.ts

@@ -14,6 +14,7 @@ import type {
   ApprovalResponse,
   BackgroundTaskInfo,
   CreateSessionOptions,
+  JsonObject,
   KimiHarness,
   PermissionMode,
   PromptPart,
@@ -195,6 +196,16 @@ function createInitialAppState(input: KimiTUIStartupInput): AppState {
   };
 }
 
+function buildSessionMetadata(cliOptions: CLIOptions): JsonObject | undefined {
+  if (cliOptions.worktreePath === undefined || cliOptions.parentRepoPath === undefined) {
+    return undefined;
+  }
+  return {
+    worktreePath: cliOptions.worktreePath,
+    parentRepoPath: cliOptions.parentRepoPath,
+  };
+}
+
 interface SendMessageOptions {
   readonly parts?: readonly PromptPart[];
   readonly imageAttachmentIds?: readonly number[];
@@ -228,6 +239,7 @@ export class KimiTUI {
   private startupNotice: string | undefined;
   private lastActivityMode: string | undefined;
   private lastHistoryContent: string | undefined;
+  private everHadSessionContent = false;
   readonly streamingUI: StreamingUIController;
   readonly authFlow: AuthFlowController;
   readonly btwPanelController: BtwPanelController;
@@ -268,6 +280,7 @@ export class KimiTUI {
         plan: startupInput.cliOptions.plan,
         model: startupInput.cliOptions.model,
         startupNotice: startupInput.startupNotice,
+        metadata: buildSessionMetadata(startupInput.cliOptions),
       },
     };
     this.options = tuiOptions;
@@ -562,6 +575,7 @@ export class KimiTUI {
       model: startup.model,
       permission: startup.auto ? 'auto' : startup.yolo ? 'yolo' : undefined,
       planMode: startup.plan ? true : undefined,
+      metadata: startup.metadata,
     };
 
     try {
@@ -1023,7 +1037,23 @@ export class KimiTUI {
   }
 
   hasSessionContent(): boolean {
-    return this.state.transcriptEntries.length > 0;
+    const hasContent = this.state.transcriptEntries.length > 0;
+    if (hasContent) {
+      this.everHadSessionContent = true;
+    }
+    return hasContent;
+  }
+
+  /**
+   * Whether any session in this TUI lifetime has had transcript content.
+   *
+   * Used for worktree cleanup: after `/new` the current session may be empty,
+   * but we must not delete a worktree that held an earlier session.
+   */
+  hasEverHadSessionContent(): boolean {
+    // Refresh the flag in case content was added since the last call.
+    this.hasSessionContent();
+    return this.everHadSessionContent;
   }
 
   async getStartupMcpMs(): Promise<number> {

apps/kimi-code/src/tui/types.ts

@@ -1,6 +1,7 @@
 import type {
   GoalChange,
   GoalSnapshot,
+  JsonObject,
   ModelAlias,
   PermissionMode,
   ProviderConfig,
@@ -199,6 +200,7 @@ export interface TUIStartupOptions {
   readonly plan: boolean;
   readonly model?: string;
   readonly startupNotice?: string;
+  readonly metadata?: JsonObject;
 }
 
 export type TUIStartupState = 'pending' | 'ready' | 'picker';