One task, one worktree, one session
The isolation unit that makes parallel agents safe instead of terrifying
Two browser tabs, one on a phone and one on a desktop, attached to the same agent session. Open a second task in the phone tab and the desktop tab silently switches to it too.
Nothing was wrong with the agent. The terminal multiplexer had one session with many windows and a single “current window” cursor, shared by every client. That bug produced a rule that has not changed since.
The unit of work
Every task gets three things with the same name:
- A git worktree beside the repo, on a branch named for the task:
code/<repo>-wt/<slug>onagent/<slug>, branched from main. - A terminal session of its own, one window, named for the project and the task.
- An agent session running inside it, started at the worktree root.
Kill any one and you can kill all three. Start a second task and none of this is shared with the first. The console that manages the machines here has a “new” button that does exactly this and a “kill” button that undoes it, removing the worktree and branch only when they are clean and have nothing unpushed.
Why worktrees and not branches
A branch switch changes the files under a running agent. A worktree does not. With worktrees, four agents can work on four tasks in the same repo at once, each with its own checkout, its own dev server on its own port, and its own uncommitted mess. The main checkout stays clean and is where you merge.
The convention on this machine puts worktrees beside the repo, not inside it, so tooling can find them with one glob and no repo ever contains another.
Stay where you were put
An agent started in a worktree should finish in that worktree. Moving a task to the main checkout “because it was easier” is how two sessions end up editing the same file. The area contract says it plainly: do not silently move a task between the canonical checkout and a worktree.
The same applies to the git stash. It is shared across every worktree of a repo, and another session may push or pop it at any moment. A bare git stash pop can hand you someone else’s changes. Prefer a temporary commit; if you must stash, tag the entry and apply it by hash.
When the session ends
A worktree with commits on it is worth something. A worktree with no commits and a clean tree is noise. The kill rule encodes that: clean and nothing ahead of the remote means remove the directory and delete the branch; otherwise leave both and let a human look. Automating the safe half and refusing the unsafe half is a pattern you will see again in Part 8.
Isolation is what lets you run agents in parallel without fear. One task, one worktree, one session, one name. Share nothing you do not have to.