Worktrees and parallel agents

What this lesson covers

L13 introduces git worktrees: separate working directories attached to the same git repository, each with its own branch checked out. Worktrees let you have main, a feature branch, a release branch, and three agent branches all simultaneously checked out in different folders, sharing one git history.

The lesson covers the mechanics (git worktree add, list, remove, prune), the comparison vs clones and vs checkout-switching, the constraints (one branch per worktree, shared database), and the four most common use cases: PR review, hotfix during a feature, side-by-side comparison, and the multi-agent fleet pattern.

L13 opens Phase 4. The lessons that follow (L14 integration patterns, L15 AI-authored commits, L16 the future of git) all assume worktrees as the foundation. This is the lesson where parallel multi-agent work goes from “annoying” to “trivial.”

By the end of L13, the reader will be able to

Explain what a git worktree is, how it differs from a clone, and how it differs from checkout-switching
Apply git worktree add <path> <branch> to create a parallel working directory on a separate branch
Use git worktree list, git worktree remove, and git worktree prune to manage worktrees over time
Identify the four most common use cases (PR review, hotfix during feature, side-by-side comparison, multi-agent fleet) and apply the appropriate worktree pattern
Recognize the constraint that the same branch cannot be checked out in two worktrees simultaneously, and choose a workaround (different branch, detached HEAD) when needed
Articulate why worktrees are uniquely well-suited to parallel AI agent workflows compared to multiple clones or branch-switching

Prerequisites

L1-L12 of T7. Specifically: branches (L5), cherry-pick and stash (L11), and the rebase patterns from L12. The worktree mental model builds on the branch concept and is most useful in workflows that involve cherry-pick and merge across branches (L11, L12).

Reading map

1: motivation scenario (mid-feature, teammate asks for PR review, the friction without worktrees)
2: what a worktree is, mechanically (shared git directory, separate working trees)
3: creating a worktree (add with existing branch, add -b with new branch, detached HEAD, tag)
4: listing, removing, pruning, locking worktrees
5: worktree vs clone, the key differences and when to prefer each
6: worktree vs checkout-switching, when worktrees are worth the slight overhead
7: use case 1, review a teammate’s PR
8: use case 2, hotfix during a feature
9: use case 3, side-by-side version comparison
10: use case 4, multi-agent fleet (the Phase 4 hook)
11: four worked examples (morning of context-switching, 4-agent fleet, removing with uncommitted changes, long-running test)
12: constraints and gotchas (one branch per worktree, submodules, hooks, IDE, disk space)
13: SVN/Mercurial/Perforce comparisons
14: a useful frame for managers and TPMs
15: L14-L16 foreshadowing
16: five team-scale scenarios (solo, startup, mid-size, OSS, multi-agent)
17: stay-calm psychology
18: closers and voice anchor

What this lesson deliberately does not cover

The bare-repo-plus-worktrees pattern (using git clone --bare and attaching worktrees to it), adjacent and powerful but a heavier setup; out of scope for L13
git worktree move, exists but rarely needed; covered in the gotchas paragraph
Worktree-specific configuration (e.g. per-worktree git config), edge case
Locking strategies for shared-disk worktrees, relevant for specific team setups, out of scope here

Estimated reading + practice time

50-70 minutes for the lesson body, plus 25-40 minutes for the practice drills. Most learners spend the most time on the 4-agent fleet drill: it’s the unique Phase 4 capability and the substrate for L14-L16.