Worktree isolation

Reading is non-destructive. When a sub-agent reads files, isolation is free — two agents can read the same file at the same time without interfering. When a sub-agent writes code, isolation has to be constructed. Two agents writing to the same checkout at the same time will produce conflicts. Sometimes git catches them. Sometimes it silently merges in ways that break the build at 11 PM and leave you with no clean state to roll back to.

Git worktrees are the construction. A worktree is a second (or third, or tenth) checkout of the same repository, sharing the same git object store but with its own working directory and HEAD. You can have ten agents each writing to their own worktree, and they cannot interfere with each other because they are physically writing to different directories.

Setting up a worktree

# Create a worktree on a new branch
git worktree add /Users/seth/projects/myrepo-agent-1 -b agent/fix-auth-tokens

# Verify both are registered
git worktree list
# → /Users/seth/projects/myrepo          abc1234 [main]
# → /Users/seth/projects/myrepo-agent-1  abc1234 [agent/fix-auth-tokens]

The agent's brief must include the worktree path explicitly. Do not rely on the agent to discover the right directory:

Working directory: /Users/seth/projects/myrepo-agent-1
Branch: agent/fix-auth-tokens
Task: In /src/auth/session.ts, change every localStorage.setItem call to use
httpOnly cookie via the setCookie helper at /src/utils/cookies.ts. Run
`npm test -- --testPathPattern=auth` after each change. Commit when all tests
pass. Do not touch files outside /src/auth/.

The agent never touches the main checkout. When it finishes, the parent reviews the diff and merges.

The cleanup pattern

Worktrees accumulate. After ten sessions, you have ten stale worktrees and branches cluttering git worktree list. Build cleanup into every brief — otherwise the list becomes archaeology:

When finished: commit your changes, then run:
  git worktree remove /Users/seth/projects/myrepo-agent-1
  git push origin agent/fix-auth-tokens
Return: the branch name and the last commit hash.

The parent then runs git merge --no-ff agent/fix-auth-tokens or opens a PR. The merge is explicit and reviewed — the agent does not merge into main.

Parallel worktrees

When you have multiple writing agents from a fan-out dispatch (l2), each agent gets its own worktree and branch:

git worktree add /Users/seth/projects/myrepo-agent-auth  -b agent/auth-refactor
git worktree add /Users/seth/projects/myrepo-agent-api   -b agent/api-cleanup
git worktree add /Users/seth/projects/myrepo-agent-tests -b agent/test-coverage

Each brief specifies a different worktree path and a different branch name. The agents write simultaneously. The parent integrates by reviewing three separate diffs, then merging or rebasing in sequence.

If you get stuck

git worktree add fails with "already exists." A previous session created the worktree and the agent crashed before removing it. Clean up manually, then re-create:

git worktree remove /Users/seth/projects/myrepo-agent-1 --force
git branch -d agent/fix-auth-tokens
git worktree add /Users/seth/projects/myrepo-agent-1 -b agent/fix-auth-tokens

The --force flag removes the worktree directory without deleting the branch — the branch still exists in the object store until you delete it explicitly with git branch -d.

The agent commits to the wrong branch because it did not verify git branch --show-current before working. Add a verification step to every brief: "First, confirm you are on branch agent/fix-auth-tokens. If git branch --show-current returns anything else, stop and return an error — do not proceed." This check costs one tool call and prevents a merge to main.

Worktree paths with spaces break some tool invocations inside the agent's context. Keep worktree directories adjacent to the main repo, no spaces in the path, named with the ticket or branch identifier.

Cross-reference

l1 establishes when to use sub-agents versus tool calls. l2 shows parallel dispatch where worktrees become essential — you cannot have multiple writing agents without multiple worktrees. l7 puts this pattern into a full PR pipeline where the worktree creation, the agent brief, and the PR open are all coordinated by the parent.

Deliverable

Create a worktree for one current branch in a real project. Write an agent brief that specifies: the worktree path, the branch name, a concrete coding task with a verifiable completion signal (a test command that exits 0, a lint check that clears), and a cleanup sequence. Run git worktree list and confirm the worktree is registered. You do not have to run the agent for this lesson — you do have to run the worktree creation command and verify the output.