Cheatsheet: Worktrees and parallel agents

Voice anchor

Git stores snapshots. Every other command is just navigating those snapshots.

Worktree command reference

Goal	Command
Create worktree with existing branch	git worktree add <path> <branch>
Create worktree with new branch	git worktree add -b <newbranch> <path> <baseref>
Create at a specific commit (detached)	git worktree add --detach <path> <sha>
Create at a tag	git worktree add <path> <tag>
List all worktrees	git worktree list
Remove a worktree	git worktree remove <path>
Force-remove (discards uncommitted)	git worktree remove --force <path>
Prune stale records	git worktree prune
Lock a worktree	git worktree lock <path> --reason "..."
Unlock a worktree	git worktree unlock <path>
Move a worktree	git worktree move <old-path> <new-path>

Choosing the right tool

Situation	Tool
”I want two branches checked out at once on my laptop”	worktree
”I want to run two copies that can drift independently”	clone
”I want to look at this PR locally for 10 minutes”	worktree
”I want a backup copy on a separate disk”	clone
”I want to spin up 6 AI agents in parallel”	6 worktrees
”I want to test something that could break my repo”	clone (or detached-HEAD worktree)
“I’m done with this branch, moving to a new one”	checkout-switching
”I’ll be jumping between branches all day”	worktrees

Multi-agent fleet pattern (the Phase 4 substrate)

# Setup (from main repo)
git checkout main && git pull
git worktree add -b agent-1/<task> ../agent-1 main
git worktree add -b agent-2/<task> ../agent-2 main
git worktree add -b agent-3/<task> ../agent-3 main
# ... up to N agents ...

# Each agent works in its own folder; commits flow into shared .git/
# Watch from main repo:
git log --all --oneline --graph

# At integration time, lead merges or cherry-picks from each agent branch
# (covered in L14)

# Teardown
git worktree remove ../agent-1
git worktree remove ../agent-2
# ...
git branch -D agent-1/<task> agent-2/<task> ...

Worktree basics drill, model walk-through

After running through the drill, you should see:

git worktree list
# /Users/you/myrepo                abc1234 [feature/your-branch]
# /Users/you/wt-test               def5678 [main]

And in ../wt-test:

git log --all --oneline
# def5678 (HEAD, main) main's tip
# new2 commit you made in original repo on feature/your-branch
# abc1234 ...

The point: --all shows commits across branches even though your current worktree is on main. Without --all, you only see main’s history.

Multi-worktree (agent simulation) drill, model walk-through

After completing the drill, your unified graph (git log --all --oneline --graph from the main repo) should look something like:

* ee5 (sim-agent-3/feature-c) feature-c commit 3
* dd4 (sim-agent-3/feature-c) feature-c commit 2
* cc3 (sim-agent-3/feature-c) feature-c commit 1
| * bb3 (sim-agent-2/feature-b) feature-b commit 2
| * aa2 (sim-agent-2/feature-b) feature-b commit 1
| | * 992 (sim-agent-1/feature-a) feature-a commit 2
| | * 881 (sim-agent-1/feature-a) feature-a commit 1
| |/
|/|
|/
* 770 (main) starting commit

Three branches diverged from main, each with their own commits. The integration step merges them back into a new branch.

Common mistakes and fixes

Mistake	Fix
Same branch in two worktrees (git rejects)	Use detached HEAD in one (--detach) or pick a different branch
Forgot which folder I’m in	Always use a clear terminal prompt; adopt a naming convention for worktree paths
Worktree won’t remove (uncommitted changes)	Commit/stash inside the worktree, OR use --force if you don’t care about the changes
Worktree records left over after manual delete	git worktree prune
Lost track of how many worktrees I have	git worktree list periodically; clean up unused ones
Disk space getting tight from many worktrees	Each worktree includes a full working tree; remove unused ones; consider partial clones for very large repos

What’s in L14

Multi-agent integration patterns: three ways to integrate work from parallel agents (shared origin, per-agent fork, shared worktrees). Lead orchestration. Semantic-conflict catching at integration. Builds directly on L13’s worktree foundation. References the Clawless 2026-06-04 sprint as a real-world example of multi-agent integration in production.