Git worktrees
Build-along · ~12 min at your own keyboard
Two agents editing the same folder step on each other. Worktrees give each agent its own copy sharing one history: agents build in parallel, you merge the winners. This lesson assumes you've used git before: commits, branches, and a merge. If not, do a git basics tutorial first (or ask Claude to walk you through one in a practice folder) — this one adds a lot on top.
The long version: Parallel work with worktrees ↗
Mac: Mac: sibling folders like ../wt-services work as written in Terminal.
Windows: Windows: use PowerShell and forward slashes in git commands. If the path has spaces, wrap it in double quotes.
Do this
0/4Checkpoints
- ▸You should now see two worktree folders listed by git worktree list.
- ▸You should now see each agent's work showing up only in its own folder.
- ▸You should now see both pieces present in the main folder after the merge.
The three ways this goes wrong
- git says the folder is not a repository. — Run git init and make one commit first. Worktrees need at least one commit.
- The merge reports a conflict. — Don't just keep both sides — they may contradict each other. Open the file, decide what the result should do, edit to that, then check it (open the page, run the tests) before you commit. Ask Claude to explain each side if the file is long.
- A worktree folder is missing after you finish. — Run git worktree list. If it is stale, git worktree prune clears it.
Share what happened
Paste your worktree list, what each agent built, and the merge result.
Strip API keys, passwords, and tokens before you paste. Swap them for [KEY].
🔒 Don't paste confidential, personal-health, or payment info.