feat(cli): add --worktree flag to create/reuse a git worktree for the TUI

.changeset/worktree-for-cli.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": minor
+---
+
+Add `kilo --worktree <name>` to create (or reuse) a git worktree and start the TUI there. Resuming an explicit `--session <id>` now tries to restart in the worktree the session was originally created in, if it still exists.

packages/opencode/src/cli/cmd/tui.ts

@@ -168,6 +168,12 @@ export const TuiThreadCommand = cmd({
         type: "boolean",
         describe: "fetch session from cloud and continue locally (use with --session)",
       })
+      // kilocode_change start - create/reuse a git worktree before starting
+      .option("worktree", {
+        type: "string",
+        describe: "create (or reuse) a git worktree with this name and start kilo there",
+      })
+      // kilocode_change end
       .option("prompt", {
         type: "string",
         describe: "prompt to use",
@@ -182,6 +188,7 @@ export const TuiThreadCommand = cmd({
     const { importCloudSession, localSessionID, validateCloudFork } = await import("@/kilocode/cloud-session")
     const { KiloTuiThreadDaemon } = await import("@/kilocode/cli/cmd/tui/thread")
     const { preload } = await import("@/kilocode/cli/cmd/tui")
+    const { resolveTuiDirectory } = await import("@/kilocode/cli/cmd/tui-worktree")
     // kilocode_change end
     const unguard = win32InstallCtrlCGuard()
     const shutdown = {
@@ -206,7 +213,14 @@ export const TuiThreadCommand = cmd({
 
       // Resolve relative --project paths from PWD, then use the real cwd after
       // chdir so the thread and worker share the same directory key.
-      const next = resolveThreadDirectory(args.project)
+      // kilocode_change start - `--worktree <name>` creates/reuses a worktree; resuming
+      // an explicit `--session <id>` tries to restart in that session's worktree
+      const next = await resolveTuiDirectory(args, resolveThreadDirectory(args.project)).catch((error) => {
+        UI.error(errorMessage(error))
+        process.exitCode = 1
+      })
+      if (!next) return
+      // kilocode_change end
       const file = await target()
       // kilocode_change start
       const preloads = preload(typeof KILO_WORKER_PATH !== "undefined", () =>

packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts

@@ -0,0 +1,129 @@
+// kilocode_change - new file
+// Supports `kilo --worktree <name>` (create/reuse a git worktree before the TUI
+// starts) and resuming an explicit `--session <id>` in the worktree it was
+// created in.
+import path from "path"
+import { Effect } from "effect"
+import { UI } from "@/cli/ui"
+import { Filesystem } from "@/util/filesystem"
+
+function slugify(name: string) {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+async function withInstance<A>(root: string, fn: (run: <T>(effect: Effect.Effect<T, any, any>) => Promise<T>) => Promise<A>) {
+  const { AppRuntime } = await import("@/effect/app-runtime")
+  const { InstanceStore } = await import("@/project/instance-store")
+  const { InstanceRef } = await import("@/effect/instance-ref")
+  const { store, ctx } = await AppRuntime.runPromise(
+    InstanceStore.Service.use((store) => store.load({ directory: root }).pipe(Effect.map((ctx) => ({ store, ctx })))),
+  )
+  const run = <T>(effect: Effect.Effect<T, any, any>) =>
+    AppRuntime.runPromise(effect.pipe(Effect.provideService(InstanceRef, ctx)))
+  try {
+    return await fn(run)
+  } finally {
+    await AppRuntime.runPromise(store.dispose(ctx))
+  }
+}
+
+type WaitResult = { ok: true } | { ok: false; message: string }
+
+/** Waits for the `worktree.ready`/`worktree.failed` event for `directory`, with
+ *  a `cancel()` handle so a caller can drop the timer/listener on early failure. */
+function waitForWorktreeEvent(
+  bus: typeof import("@/bus/global").GlobalBus,
+  event: typeof import("@/worktree").Worktree.Event,
+  directory: string,
+  timeoutMs: number,
+) {
+  const deferred = Promise.withResolvers<WaitResult>()
+  let handler = (_e: { directory?: string; payload?: any }) => {}
+  const cleanup = () => {
+    clearTimeout(timer)
+    bus.off("event", handler)
+  }
+  const timer = setTimeout(() => {
+    cleanup()
+    deferred.resolve({ ok: false, message: "Timed out waiting for the worktree to finish setting up" })
+  }, timeoutMs)
+  timer.unref?.()
+  handler = (e) => {
+    if (e.directory !== directory) return
+    if (e.payload?.type === event.Ready.type) {
+      cleanup()
+      deferred.resolve({ ok: true })
+    } else if (e.payload?.type === event.Failed.type) {
+      cleanup()
+      deferred.resolve({ ok: false, message: e.payload.properties?.message ?? "Worktree setup failed" })
+    }
+  }
+  bus.on("event", handler)
+  return { promise: deferred.promise, cancel: cleanup }
+}
+
+async function resolveWorktree(name: string, root: string, timeoutMs = 10 * 60_000) {
+  const { Worktree } = await import("@/worktree")
+  const { GlobalBus } = await import("@/bus/global")
+  const slug = slugify(name)
+  if (!slug) throw new Error(`Invalid worktree name "${name}"`)
+  return withInstance(root, async (run) => {
+    const existing = await run(Worktree.Service.use((svc) => svc.list()))
+    // list() remaps `name` to the project ID when a worktree's basename collides
+    // with the primary checkout's basename, so also match on the directory itself.
+    const found = existing.find(
+      (w) => w.name.toLowerCase() === slug || path.basename(w.directory).toLowerCase() === slug,
+    )
+    if (found && (await Filesystem.exists(found.directory))) {
+      UI.println(`Using existing worktree "${found.name}" at ${found.directory}`)
+      return found.directory
+    }
+
+    const info = await run(Worktree.Service.use((svc) => svc.makeWorktreeInfo({ name })))
+    UI.println(`Creating worktree "${info.name}"...`)
+    const wait = waitForWorktreeEvent(GlobalBus, Worktree.Event, info.directory, timeoutMs)
+    await run(Worktree.Service.use((svc) => svc.createFromInfo(info))).catch((error) => {
+      wait.cancel()
+      throw error
+    })
+    const result = await wait.promise
+    if (!result.ok) throw new Error(`Failed to create worktree "${info.name}": ${result.message}`)
+    UI.println(`Worktree ready at ${info.directory}`)
+    return info.directory
+  })
+}
+
+async function resolveSessionWorktree(sessionID: string, fallback: string) {
+  try {
+    const { AppRuntime } = await import("@/effect/app-runtime")
+    const { Session } = await import("@/session/session")
+    const { SessionID } = await import("@/session/schema")
+    const { Schema } = await import("effect")
+    const session = await AppRuntime.runPromise(
+      Session.Service.use((svc) => svc.get(Schema.decodeUnknownSync(SessionID)(sessionID))),
+    )
+    if (!session.directory || session.directory === fallback) return fallback
+    if (!(await Filesystem.exists(session.directory))) return fallback
+    UI.println(`Resuming session in its original worktree: ${session.directory}`)
+    return session.directory
+  } catch {
+    // Unknown session, missing directory, or lookup failure: fall back to the
+    // resolved cwd and let normal session validation report the real error.
+    return fallback
+  }
+}
+
+/**
+ * Resolves the directory to launch the TUI in: creates/reuses `--worktree
+ * <name>`, or when resuming an explicit `--session <id>` without `--project`,
+ * tries that session's original worktree. Otherwise returns `root` unchanged.
+ */
+export function resolveTuiDirectory(args: { worktree?: string; session?: string; project?: string }, root: string) {
+  if (args.worktree) return resolveWorktree(args.worktree, root)
+  if (args.session && !args.project) return resolveSessionWorktree(args.session, root)
+  return Promise.resolve(root)
+}