Worktrees

A git worktree is a second checkout of the same repo on its own branch. Give each parallel agent one and their edits never collide.

The model

Worktrees live at <repo>/.agents/worktrees/<terminal-id> on branch agents/<terminal-id>. Each is a full working copy sharing the same .git, so an agent can build, test, and commit in complete isolation from your main checkout and from every other teammate.

Provision, release, prune

agents worktree manages the lifecycle directly. Provision creates (or reuses) one and prints its absolute path; release removes it once it is clean and merged or pushed; prune sweeps every safe-to-remove worktree at once.

# Create (or reuse) an isolated worktree — prints the path
agents worktree provision CC-1747509823-3

# Remove it if clean and the branch is merged or has no unpushed commits
agents worktree release CC-1747509823-3

# Preview what prune would release across all agent worktrees
agents worktree prune --dry-run

# Release every agent worktree that is safe to remove
agents worktree prune

release and prune refuse to touch a dirty or unpushed worktree — your in-progress work is never discarded. release --force skips the safety checks, which discards unpushed work, so reach for it only when you mean to.

Worktrees under teams

Teams provision worktrees for you. Turn on isolation at create time with --enable-worktrees, then hand each teammate a dedicated worktree with --worktree <role>. Name it after the surface the teammate owns.

agents teams create parallel-refactor --enable-worktrees

agents teams add parallel-refactor claude \
  "Refactor auth module" --name auth --worktree refactor-auth

agents teams add parallel-refactor codex \
  "Refactor billing module" --name billing --worktree refactor-billing

agents teams start parallel-refactor --watch

Each worktree name must be unique per teammate — two teammates cannot share one, since the second checkout would fail. Teammates that genuinely must co-edit the same files are not independent: collapse them into one teammate rather than splitting and re-sharing.

Cleanup

Team worktrees are released automatically on teams stop or teams disband, unless a worktree still has uncommitted changes — in which case it is kept and reported so nothing is lost. For worktrees you provisioned by hand, run agents worktree prune to reclaim the clean ones.

Related: Teams, Sessions.