Worktrees

Worktrees

Task cards run in isolated git worktrees so agent edits stay separated until merge time.

What a task worktree is

Task-agent worktrees are per-card git checkouts created so each agent can edit in isolation. The worktree service lives in src/worktrees/ and crates/refact-worktrees/, and task-agent tools build on top of that service.

The practical result is:

• one card → one agent chat → one worktree
• branch names encode task/card identity
• merge is a deliberate step, not an implicit side effect

Why isolation matters

Isolation prevents agents from trampling each other's changes, makes diffs easier to inspect, and gives the planner a clean decision point before merge. It also gives the system a safe cleanup target if an agent stalls or fails.

The task tool code relies on this separation when it:

• spawns agents
• collects diffs
• merges ready work
• cleans up after merge or failure

Branch naming

The code uses task/card-specific branch names of the form:

refact/task/<task>/card/<T-N>/<hash>

You can see this pattern in task-agent and A/B flows. The exact suffix depends on the workflow, but the task and card identifiers are embedded in the branch name so the branch is traceable back to the board.

Lifecycle: create, merge, clean up

The worktree service can:

• create the worktree and branch
• record registry metadata
• merge the worktree back to the target branch
• remove the worktree directory
• delete the branch
• delete the registry record

The task merge path is designed to squash-merge to main by default, with cleanup after a successful merge or a no-op merge state. The merge result messages also include cleanup information.

Registry and cleanup

The registry is persisted under the worktree cache directory and tracks worktree metadata. Cleanup removes the practical traces of the worktree after merge:

• worktree directory deleted
• branch deleted when appropriate
• registry entry removed

That keeps the registry from accumulating stale entries and makes abandoned worktrees recoverable or removable.

Rescue pattern for stuck agents

The code includes helpers that detect abandoned worktrees and make it possible to recover or clean up stale state. In practice, the rescue pattern is:

1. inspect the card and its agent state
2. use planner tools like check_agents, agent_diff, or agent_pulse
3. if the agent is stuck, steer it or stop it
4. if needed, restart, mark failed, or clean up the worktree

The important point is that the worktree is a recoverable artifact, not the source of truth; the board/card state remains the planner's control plane.

Flow summary

flowchart LR
  A[Planner spawns card agent] --> B[WorktreeService creates isolated worktree]
  B --> C[Agent edits branch]
  C --> D[Planner inspects diff/status]
  D --> E[Merge to main]
  E --> F[Delete worktree]
  F --> G[Delete branch]
  G --> H[Delete registry record]

Loading

See also

• Task Planner and Cards