Move a worktree thread (and its changes) to the current checkout

[EduardoDadalt]

Problem

T3 Code makes it easy to start work in a worktree, and agents can hand a thread from the
current checkout into a new worktree (t3_worktree_handoff). There is no way back.

When work started in a worktree should continue in the project's own folder (to run the
real dev environment, use a tool that is only set up there, or just stop juggling a
second checkout), today you have to do it by hand:

1. commit/stash whatever is in the project checkout,
2. detach or remove the worktree so its branch can be checked out elsewhere,
3. check the branch out in the project folder and carry the uncommitted changes over,
4. and the thread keeps pointing at the old worktree path, so it can't follow.

Step 4 has no manual workaround: the thread stays bound to the worktree.

Proposal

A thread action, Move to current checkout, available for idle threads that work in
a worktree (sidebar right-click menu and the chat header's thread menu on web/desktop).
It:

• checks out the worktree's branch in the project folder (detached commit if the
  worktree was detached), so commits made in the worktree come along;
• brings over the worktree's uncommitted changes — modifications, deletions, and new
  files — as ordinary unstaged edits;
• re-points the thread at the project checkout (worktreePath: null), so the next turn
  runs there;
• removes the worktree.

Files ignored by Git (.env, node_modules) are not moved, and the dialog says so.

Never overwrite local work

• If the project checkout has uncommitted changes, the move refuses unless the user
  picks Commit (with a message), Stash, or Discard in the dialog.
• The worktree's state is captured to a hidden ref (reusing the checkpoint capture)
  before anything changes, so a failure can't lose the work being moved.
• Changes are applied with git read-tree -m -u, which refuses to overwrite files that
  differ from what it expects.
• Every step rolls back the earlier ones if a later one fails (including the thread
  metadata update), leaving the worktree on its branch with its changes and the
  checkout on its original branch.
• Refused while the thread is running/queued, or when another thread still uses the
  same worktree.

Shape

• One server service method (git.moveThreadToLocalCheckout RPC), so the same
  capability could later be exposed as an MCP tool, the reverse of
  t3_worktree_handoff.
• Gated by an environment capability so app.t3.codes hides it against older servers.
• Proposed scope for a first PR: web + desktop only. Mobile and an MCP tool could follow
  if wanted.

I have a working implementation with tests against real Git repositories (full move,
dirty-checkout refusal, stash, rollback on failure) and would be happy to open a PR if
the direction and scope sound right.

Questions for maintainers

1. Is a "move back to current checkout" action something you want in T3 Code?
2. Should the worktree be removed after a successful move, or left (detached) for the
   existing worktree cleanup to handle?
3. Is offering Commit / Stash / Discard for a dirty checkout the right UX, or should the
   move simply refuse and let the user clean up first?
4. Web/desktop first, or should mobile and the MCP tool be part of the same change?

Update (2026-10-14): the proposal now covers moving into any existing worktree of the project, not only the current checkout, following the points from #19295. See this comment for the current behavior and proposed scope. The original proposal follows unchanged.

[LAlex14]

Julius closed my #19295 as a duplicate of this, so adding my points here. My case is a bit wider, Docker is set up in only one of my worktrees and that is not always the main checkout, so I think the target should be any existing worktree, not only the project checkout.

For a dirty target I would refuse with a clear message that lists the changed files, your Commit/Stash/Discard dialog works for me too. If the target is on another branch, switching it to the thread's branch automatically and remembering the old one would save a step. When the source is another worktree and not the main one, I would rather keep it detached than remove it.

Also, a worktree change detaches the Claude session and kills background agents (#16000), so I think this move should reuse the same background-work guard. +1 on opening the PR, I would use this daily.

[EduardoDadalt]

Thanks @LAlex14, these all made sense, so I reworked the implementation around them. The action is now Move to worktree…:

• Any existing worktree as the target. The dialog lists the project's other worktrees, detached ones included, with the current checkout first. The source is still a thread that works in a worktree, since moving out of the project checkout would affect every other thread working there.
• Dirty target. The dialog lists the target's changed files and offers Commit / Stash / Discard. If the server refuses a dirty target, its message names the files too. The changes are only applied to a clean target, and any failure rolls back every earlier step, so there is no stash-pop conflict to leave behind.
• Target on another branch. It is switched to the thread's branch automatically. The dialog says which branch it switches from, and the confirmation repeats it.
• The worktree the thread leaves. The dialog has a "Remove after moving" option. It is checked when moving to the current checkout and unchecked when moving between worktrees. If kept, the source worktree stays detached and clean: the moved changes leave it, and ignored files stay. I made it a choice because nothing else would ever offer to clean up a detached worktree that no thread points at.
• Background work ([Bug]: Runtime-mode, instance and worktree changes detach the Claude session and kill live subagents without the background-work check #16000). The move is refused while the thread still has background agents or commands, with a retryable "wait or press Stop" message, because re-pointing the thread detaches the provider session that runs them. It is also refused while another thread is running in the target. This guards only this action; the general [Bug]: Runtime-mode, instance and worktree changes detach the Claude session and kill live subagents without the background-work check #16000 fix is a separate problem.

Updated answers to my original questions:

1. Unchanged.
2. Now a choice in the dialog, with the defaults above.
3. Commit / Stash / Discard, with the changed files listed.
4. Still web + desktop first.

The implementation, with tests against real Git repositories, is on my fork: https://github.com/EduardoDadalt/t3code

Could a maintainer confirm whether this direction and scope are OK for a PR? Proposed scope: web and desktop, one server service method behind git.listThreadMoveTargets / git.moveThreadToWorktree, and gated by an environment capability. Mobile and an MCP tool (the reverse of t3_worktree_handoff) would be follow-ups. Happy to narrow it, for example back to the current checkout only, if you'd rather start smaller.