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

[bagatao-anaconda]

Issue

https://docs.google.com/document/d/1eXKc_A9f_mVuc3LiniP3gbLWm7Ic_cPe58z1Tq_ZlzY/edit?pli=1&tab=t.0#heading=h.t3eix4ujj88t

Context

kilo had no way to open the TUI directly inside an isolated git worktree, no way to manage those worktrees from the CLI or TUI once created, and resuming a session always assumed you were already in (or navigated back into) the directory it was created in. This adds kilo --worktree <name> to spin up (or reuse) a worktree and launch straight into it, kilo worktree create/list/remove as non-interactive counterparts for scripting, a /worktree alias in the TUI to list/remove worktrees, and makes explicit --session <id> resume follow the session back into its original worktree when possible.

Implementation

• kilo --worktree <name>: added to the default TUI command ($0 [project]). Before process.chdir, the resolved directory now goes through resolveTuiDirectory(args, root) in the new Kilo-owned src/kilocode/cli/cmd/tui-worktree.ts, keeping the shared tui.ts diff to a single option registration, one lazy import, and one small integration block.
• Placement: worktrees are created at .kilo/worktrees/<slug> inside the primary checkout — matching where the VS Code extension's Agent Manager (WorktreeManager.ts) already places its own worktrees — with a plain <slug> branch name (no opencode/ prefix), and a .git/info/exclude entry so the directory doesn't show up in git status.
• Reuse and cleanup, built entirely on the existing Worktree.Service (src/worktree/index.ts) — no new git plumbing:
  • Trusts neither the git registration nor the on-disk directory alone: a directory can exist without a live registration (orphaned), and a registration can outlive its directory (deleted out-of-band, or pruned via git worktree prune). Reclaims a dead registration (and its branch) before recreating under the same name.
  • Before creating, clears a leftover branch of the same name (e.g. left behind by git worktree prune, which drops the registration but never deletes the branch) using git branch -d — never -D — so it can never silently discard unmerged work from an interrupted worktree or an unrelated branch that happens to share the name; surfaces git's own refusal instead.
  • Refuses to create a worktree from inside another worktree, since that would nest .kilo/worktrees/<name> inside it and branch off the wrong HEAD.
• Readiness: added a new worktree.setup.ready event (packages/schema/src/worktree-event.ts, emitted from worktree/index.ts) that fires once the project's start script finishes, not just checkout — the CLI waits for this before returning, with a 10-minute timeout that's cancelled if creation itself rejects, so a failed creation exits immediately instead of leaving a dangling timer.
• kilo worktree create/list/remove (new src/kilocode/cli/cmd/worktree.ts, registered via the existing KiloCli.register() hook — zero shared-file diff for this part): create reuses resolveWorktree directly, so it gets all of the above (idempotent reuse, stale-registration reclaim, safe branch handling, nested-worktree rejection) for free. list/remove match by name or directory basename against Worktree.Service.list().
• TUI /worktree//worktrees: added as slash aliases on the existing (experimental, KILO_EXPERIMENTAL_WORKSPACES-gated) workspaces dialog, since worktrees are already listed/removable there via the same Worktree.Service.
• Session resume: when --session <id> is passed without --project, the session's stored directory is looked up via a lightweight, disposable Database-only layer (not the full AppRuntime/instance graph, since --session is a common flag and shouldn't pay for bootstrapping Plugin/LSP/MCP/Provider/etc just for this) and used instead of the cwd if it still exists on disk. Any lookup failure falls back silently to the current directory so normal session validation still reports the real error.
• Added a changeset (@kilocode/cli, minor).

Screenshots / Video

How to Test

Manual/local verification

• Ran bun run typecheck, bun run lint, bun test, and bun run script/check-opencode-annotations.ts — all clean (agent-executed).
• End-to-end smoke tests against real git repos, using the built binary (agent-executed):
  • kilo --worktree feature-x: created .kilo/worktrees/feature-x on branch feature-x, waited for the setup-ready event, and launched the TUI rooted there. Re-running reused the existing worktree.
  • Deleted the worktree directory out-of-band + git worktree prune (leaving a stale, unmerged branch): re-running with the same name correctly refused (Branch "feature-x" already exists... not fully merged) instead of discarding the commit; after removing the branch normally, re-running recreated it under the same name.
  • kilo --worktree "!!!" (name that slugifies to empty): failed fast with Invalid worktree name "!!!".
  • Running --worktree <name> from inside another worktree: correctly refused with a message pointing at the primary checkout.
  • kilo worktree create/list/remove: full cycle verified against the real binary, including reuse and post-remove git state (git worktree list / git branch --list show no leftovers).
  • kilo --session <id> from a different directory: correctly resumed in the session's original worktree.

Reviewer test steps

1. From a git repo, run kilo --worktree my-feature.
2. Confirm the TUI starts with a new worktree/branch (visible in the TUI's footer directory/branch indicator) at .kilo/worktrees/my-feature.
3. Exit and re-run the same command; confirm it prints "Using existing worktree" and reuses the same directory instead of creating a new one.
4. Run kilo worktree list and kilo worktree remove my-feature; confirm it's gone from git worktree list.
5. Start a session in a worktree, exit, then from the main checkout run kilo --session <that-session-id>; confirm it resumes in the worktree directory rather than the main checkout.
6. (Optional, requires KILO_EXPERIMENTAL_WORKSPACES=1) In the TUI, type /worktree and confirm it opens the workspaces dialog listing worktrees.

[kilo-code-bot]

Code Review Summary

Status: 6 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	5

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/opencode/src/kilocode/cli/cmd/worktree.ts	59	(new) kilo worktree list writes its data rows to stderr via UI.println, so piping/$(...) captures nothing — scriptable output belongs on stdout like kilo session list

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/cli/cmd/worktree.ts	43	(new) worktree create discards the directory resolveWorktree returns — printing it on stdout would make the command composable
packages/opencode/src/kilocode/cli/cmd/worktree.ts	83	(new) kilo worktree remove also force-deletes the worktree's branch (git branch -D in Worktree.Service.remove) with no confirmation or hint
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	48	(carried) Effect.Effect<T, any, any> in withInstance's run signature disables Effect requirement/error checking
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	138	(carried) Failed stale-registration reclaim is a dead end — no git worktree prune fallback or remediation hint
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	212	(carried) routing/reuse logic still untested — tests cover only slugify/ensureGitExclude

Files Reviewed (5 files)

Incremental review of commits since 7c25f5b (head 91747c0; the range includes an origin/main merge — only PR-owned files were reviewed).

• packages/opencode/src/kilocode/cli/cmd/worktree.ts - 3 issues (new kilo worktree create/list/remove command)
• packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts - 0 new issues (resolveWorktree export for the create command is clean)
• packages/opencode/src/kilocode/cli/setup.ts - 0 issues
• packages/tui/src/app.tsx - 0 issues (/worktree aliases correctly gated behind KILO_EXPERIMENTAL_WORKSPACES via the palette visibility filter)
• .changeset/worktree-for-cli.md - 0 issues

Fix these issues in Kilo Cloud

Previous Review Summaries (5 snapshots, latest commit 7c25f5b)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 7c25f5b)

Status: 3 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	3

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	48	(carried) Effect.Effect<T, any, any> in withInstance's run signature disables Effect requirement/error checking
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	136	(carried) Failed stale-registration reclaim is a dead end — no git worktree prune fallback or remediation hint
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	208	(carried) routing/reuse logic still untested — tests cover only slugify/ensureGitExclude; the nested-worktree guard and branch-reclaim logic are also untested

Files Reviewed (3 files)

Incremental review of commits since 90989d4 (head 7c25f5b, includes a merge of origin/main that left the PR-owned files untouched).

• packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts - 3 issues (all carried; new changes — logged exclude-write failures, runGit dedup — are clean)
• packages/opencode/test/event-manifest.test.ts - 0 issues
• packages/opencode/test/kilocode/cli/cmd/tui-worktree.test.ts - 0 issues

Fix these issues in Kilo Cloud

Previous review (commit 90989d4)

Status: 3 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	3

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	43	(carried) Effect.Effect<T, any, any> in withInstance's run signature disables Effect requirement/error checking
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	131	(carried) Failed stale-registration reclaim is a dead end — no git worktree prune fallback or remediation hint
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	208	(carried) routing/reuse logic still untested — tests cover only slugify/ensureGitExclude; the nested-worktree guard and branch-reclaim logic are also untested

Files Reviewed (7 files)

• packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts - 3 issues
• packages/opencode/src/worktree/index.ts - 0 issues
• packages/schema/src/worktree-event.ts - 0 issues
• packages/opencode/src/cli/cmd/tui.ts - 0 issues
• packages/opencode/test/kilocode/cli/cmd/tui-worktree.test.ts - 0 issues
• .changeset/worktree-for-cli.md - 0 issues
• bun.lock - 0 issues

Fix these issues in Kilo Cloud

Previous review (commit 627e24d)

Status: 4 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	3

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	145	git branch -D force-deletes any pre-existing local branch named <slug>, silently discarding unmerged work (the user's own branch, or an unmerged leftover from a pruned worktree)

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	131	(carried) Failed stale-registration reclaim is a dead end — no git worktree prune fallback or remediation hint
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	42	(carried) Effect.Effect<T, any, any> still disables requirement checking
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	205	(carried) routing/reuse logic still untested — tests cover only slugify/ensureGitExclude; the new nested-worktree guard and branch-reclaim logic are also untested

Files Reviewed (5 files)

• packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts - 4 issues
• packages/opencode/src/worktree/index.ts - 0 issues
• packages/opencode/test/kilocode/cli/cmd/tui-worktree.test.ts - 0 issues
• packages/opencode/src/cli/cmd/tui.ts - 0 issues
• .changeset/worktree-for-cli.md - 0 issues

Fix these issues in Kilo Cloud

Previous review (commit 0d78791)

Status: 5 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	4

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	132	Branch collisions unhandled: a pre-existing branch <slug> fails every run with no recovery path

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	124	Failed stale-registration reclaim is a dead end — no git worktree prune fallback or remediation hint
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	103	Invoking from inside a linked worktree nests the new worktree inside it
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	45	(carried) Effect.Effect<T, any, any> still disables requirement checking
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	179	(carried) routing/reuse logic still untested — new tests cover only slugify/ensureGitExclude

Resolved since last review

• Full AppRuntime bootstrap on --session resume → now a scoped Database-only read
• Stale worktree registrations → reclaimed via Worktree.Service.remove
• worktree.ready fired before start scripts → new worktree.setup.ready event emitted after runStartScripts
• unref()'d timeout → timer now stays ref'd

Files Reviewed (5 files)

• packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts - 5 issues
• packages/opencode/src/worktree/index.ts - 0 issues (additive SetupReady event, properly marked)
• packages/opencode/test/kilocode/cli/cmd/tui-worktree.test.ts - 0 issues
• packages/opencode/src/cli/cmd/tui.ts - 0 issues (unchanged since last review)
• .changeset/worktree-for-cli.md - 0 issues

Fix these issues in Kilo Cloud

Previous review (commit 907f7df)

Status: 6 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	4

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	106	AppRuntime.runPromise builds the whole AppLayer in the launcher process on every kilo --session <id> just to read one session row, and the runtime is never disposed (startup latency + resident resources alongside the TUI worker's own runtime)
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	81	Stale worktree registrations are never pruned: the leftover opencode/<slug> branch makes candidate() rename the new worktree to <slug>-<random> and dead entries accumulate on every re-run

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	95	worktree.ready is emitted before runStartScripts, so "Worktree ready"/TUI start is not gated on the project's start script finishing (contradicts the PR description)
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	54	timer.unref?.() defeats the timeout guarantee — a stalled bootstrap can exit silently with status 0 instead of reporting the timeout
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	18	InstanceStore.provide already implements withInstance; Effect.Effect<T, any, any> disables requirement checking
packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts	125	No test under packages/opencode/test/kilocode/ for the new routing/slug/reuse logic

Files Reviewed (3 files)

• packages/opencode/src/kilocode/cli/cmd/tui-worktree.ts - 6 issues
• packages/opencode/src/cli/cmd/tui.ts - 0 issues (shared-file diff is minimal: one option, one lazy import, one integration block)
• .changeset/worktree-for-cli.md - 0 issues

Fix these issues in Kilo Cloud

---

_{Reviewed by kimi-k3 · Input: 67.5K · Output: 13.3K · Cached: 880.4K}

_{Review guidance: REVIEW.md from base branch main}

[marius-kilocode]

We should rather focus on something that upstream already does to ensure no duplicate implementation.

[bagatao-anaconda]

@marius-kilocode Can you clarify what you have in mind regarding the reuse of upstream features/code?

I looked around a bit and couldn't find a --worktree equivalent CLI flag in the upstream repository (or official CLI docs at https://opencode.ai/docs/cli). The TUI only seems to support --dir, --continue, --session, --fork, --cloud-fork flags.

[bagatao-anaconda]

@marius-kilocode For more context, I checked kilocode-legacy. The worktree feature existed there in two generations, and neither depended on upstream opencode (legacy predates the opencode fork entirely, so there was no "upstream" to duplicate against at the time):

• Gen 1 (in the old cli/ package, --parallel/--existing-branch flags): hand-rolled simple-git calls, worktrees dumped in os.tmpdir(), destroyed on /exit. No session ↔ worktree identity (resuming just meant re-creating a worktree on the same branch name).

• Gen 2 (PR Migrate worktree and git logic from CLI to agent manager #4643, "Migrate worktree and git logic from CLI to agent manager"): legacy's own team moved worktree ownership out of the CLI and into the extension. This became the direct ancestor of today's Agent Manager (.kilocode/worktrees/<branch>, later .kilo/worktrees/, with a .kilocode/session-id file for real resume-by-session).
  That migration commit is a useful precedent for your point: the project has already decided once that "the extension should own worktrees, not the CLI." That's exactly what today's Agent Manager does.

On upstream duplication specifically: upstream opencode has no --worktree-equivalent CLI flag today. So this PR isn't duplicating an upstream opencode feature. What it does build on is packages/opencode/src/worktree/index.ts, which is an upstream-owned Worktree.Service that already existed in the CLI but had no consumer until now (Agent Manager never touches it; it has its own separate simple-git-based WorktreeManager.ts in packages/kilo-vscode).

What I did about the real overlap (Agent Manager vs. this CLI flag): I made the CLI's --worktree place worktrees at the exact same location and with the same semantics Agent Manager uses (<repo>/.kilo/worktrees/<name>, same git-exclude handling, blocks until the setup script finishes like Agent Manager does), so a repo has one consistent worktree location regardless of which client created it.

I could not make them share the literal same code path in this PR: packages/kilo-vscode has no dependency on packages/opencode today (it bundles/spawns the CLI as a binary and talks to it over HTTP, never imports its TypeScript). True code-sharing would mean either adding that cross-package dependency or exposing worktree ops over the kilo serve HTTP API Agent Manager already talks to. Both are separate, larger initiatives I'd flag as follow-up work rather than scope-creep this PR.

[bagatao-anaconda]

Manual Test Plan — PR #12809: --worktree flag + --session worktree resume

PR: #12809

Setup

• From packages/opencode/, run bun install if needed, then confirm bun run typecheck passes on this branch.
• Use bun run dev -- <args> (from packages/opencode/) as the CLI entrypoint for every step below, e.g. bun run dev -- --worktree feature-x --project /path/to/sandbox-repo.
• Use a scratch git repo for testing (any real repo works, but a throwaway one avoids polluting a real checkout): git init sandbox-repo && cd sandbox-repo && git commit --allow-empty -m init.

1. Basic worktree creation

• Run kilo --worktree my-feature --project <sandbox-repo>.
• Confirm console prints Creating worktree "my-feature"... then Worktree ready at <path>.
• Confirm the TUI launches rooted at <sandbox-repo>/.kilo/worktrees/my-feature.
• Confirm a new branch named my-feature was created (git worktree list from the primary checkout, or check the TUI's directory/branch footer indicator).

2. Reuse an existing worktree

• Exit the TUI from step 1, then re-run the exact same command.
• Confirm it prints Using existing worktree "my-feature" at <path> (no new branch/dir created).
• Confirm git worktree list still shows only one worktree for my-feature.

3. Name slugification

• Run kilo --worktree "My Feature!!".
• Confirm the resulting directory/branch is slugified to my-feature (lowercased, spaces → dashes, punctuation stripped).
• Run it a second time with a different casing/spacing that slugifies to the same value (e.g. "my feature") and confirm it's treated as the same worktree ("Using existing worktree...").

4. Invalid name (empty after slugify)

• Run kilo --worktree "!!!".
• Confirm it fails fast (a couple seconds, not hanging) with Invalid worktree name "!!!" and a non-zero exit code — no TUI should launch.

5. Directory exists but isn't a registered worktree

• Manually create <repo>/.kilo/worktrees/blocked as a plain directory (not via git worktree add).
• Run kilo --worktree blocked.
• Confirm it errors with "<path>" already exists but is not a registered git worktree. and does not delete or touch the directory.

6. Directory deleted out-of-band, registration stale

• From step 1's worktree, exit the TUI, then rm -rf the my-feature directory directly (bypassing git worktree remove).
• Run kilo --worktree my-feature again.
• Confirm it detects the dead registration, reclaims it, and creates a fresh worktree/branch rather than trying to chdir into the missing path or erroring.

7. Pruned worktree, orphaned branch

• Create a worktree (--worktree leftover), exit, then run git worktree remove --force <path> followed by git worktree prune from the primary checkout (this drops the registration/dir but the underlying git internals can leave refs/heads/leftover behind depending on how it's removed — if the branch still exists, proceed; otherwise skip and note it).
• Run kilo --worktree leftover again.
• Confirm it successfully deletes the stale branch (git branch -d leftover) and creates a new worktree, rather than failing with "branch already exists".
• Separately: manually create an unrelated branch named leftover with unmerged commits (no worktree), then run kilo --worktree leftover. Confirm it refuses with a message telling you to git branch -D leftover yourself, instead of silently discarding the branch.

8. Refuse nesting inside another worktree

• From inside a worktree created in step 1 (cd <repo>/.kilo/worktrees/my-feature), run kilo --worktree nested.
• Confirm it refuses with Cannot create worktree "nested" from inside another worktree (...). Run this from the primary checkout at ... instead. and does not create anything.

9. .git/info/exclude is kept clean

• After any successful worktree creation, check <repo>/.git/info/exclude.
• Confirm it contains exactly one .kilo/worktrees/ entry (run creation twice/three times across different tests to confirm no duplicate lines get appended).
• Confirm git status in the primary checkout does not show .kilo/worktrees/ as untracked.

10. --session resume follows the original worktree

• In the worktree from step 1, start a session and note its session ID (visible in the TUI, or via kilo history/logs).
• Exit, cd back to the primary checkout (not the worktree).
• Run kilo --session <that-session-id> (no --project).
• Confirm it prints Resuming session in its original worktree: <path> and the TUI launches rooted in the worktree directory, not the primary checkout.

11. --session resume when worktree directory is gone

• Delete the worktree directory used in step 10 (rm -rf).
• Run kilo --session <same-session-id> again from the primary checkout.
• Confirm it silently falls back to the current directory (no crash) and that normal session-resume validation reports its usual error for a session whose files/context don't match.

12. --session + --project together bypasses worktree resolution

• Run kilo --session <session-id> --project <primary-checkout> explicitly.
• Confirm it does not attempt to resolve/resume into the worktree (per the code, worktree-follow only applies when --project is omitted) — it should just resume in the given --project directory as before this PR.

13. --worktree and --session/--project sanity

• Confirm --worktree takes precedence when passed together with --session (per implementation, args.worktree is checked first).
• Confirm normal kilo (no --worktree, no --session) behavior is completely unchanged (regression check).

14. Non-git directory

• Run kilo --worktree x --project /tmp (a plain directory, not a git repo).
• Confirm it fails with a reasonable git-related error rather than crashing or hanging.

Agreed to merge this in as is, and have obtained approval from another colleague.