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

.changeset/add-worktree-flag.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": minor
+---
+
+Add `-w, --worktree [name]` flag to create a new git worktree for the session.

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

@@ -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,

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,
@@ -136,6 +138,18 @@ export async function runShell(
     const hasContent = tui.hasSessionContent();
     setCrashPhase('shutdown');
     trackLifecycle('exit', { duration_s: (Date.now() - startedAt) / 1000 });
+
+    // Clean up the git worktree for empty sessions so abandoned worktrees
+    // do not accumulate.
+    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`);

apps/kimi-code/src/main.ts

@@ -27,6 +27,7 @@ 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 { 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 +39,17 @@ 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);
+  process.chdir(worktreePath);
+  return { worktreePath, parentRepoPath: repoRoot };
+}
+
 export async function handleMainCommand(opts: CLIOptions, version: string): Promise<void> {
   let validated: ReturnType<typeof validateOptions>;
   try {
@@ -50,6 +62,20 @@ export async function handleMainCommand(opts: CLIOptions, version: string): Prom
     throw error;
   }
 
+  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;
+    }
+  }
+
   const preflightResult = await runUpdatePreflight(
     version,
     validated.uiMode === 'print' ? { track, isTTY: false } : { track },
@@ -58,12 +84,26 @@ export async function handleMainCommand(opts: CLIOptions, version: string): Prom
     process.exit(0);
   }
 
-  if (validated.uiMode === 'print') {
-    await runPrompt(validated.options, version);
-    return;
-  }
+  try {
+    if (validated.uiMode === 'print') {
+      await runPrompt(validated.options, version);
+      return;
+    }
 
-  await runShell(validated.options, version);
+    await runShell(validated.options, version);
+  } catch (error) {
+    // If the runner failed during startup after we created a worktree, the
+    // worktree is still empty (no session ran), so clean it up to avoid leaks.
+    if (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[];
@@ -268,6 +279,7 @@ export class KimiTUI {
         plan: startupInput.cliOptions.plan,
         model: startupInput.cliOptions.model,
         startupNotice: startupInput.startupNotice,
+        metadata: buildSessionMetadata(startupInput.cliOptions),
       },
     };
     this.options = tuiOptions;
@@ -562,6 +574,7 @@ export class KimiTUI {
       model: startup.model,
       permission: startup.auto ? 'auto' : startup.yolo ? 'yolo' : undefined,
       planMode: startup.plan ? true : undefined,
+      metadata: startup.metadata,
     };
 
     try {

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';