Lesson 7 of 9 · about 15 minutes

Parallel sessions with worktrees

One repository, several folders, one branch each, so two agents never trip over each other.

Why one folder isn't enough

Your penguins-lab folder is a single working tree, and it can have only one branch checked out at a time. Say one Claude session is working on add-species-plot and you git switch the folder to another branch for a second task. Now the first session's files change underneath it. If you skip the switch and run both sessions in the same folder, they edit the same files on the same branch. Either way the work collides.

The fix is a worktree: an extra folder attached to the same repository, with its own branch checked out. Git calls this managing "multiple working trees attached to the same repository." All worktrees share commits and branches, and each has its own HEAD and index.1 Claude Code's best-practices guide recommends worktrees for exactly this: "run separate CLI sessions in isolated git checkouts so edits don't collide."3

Plain git: git worktree

$ git worktree add ../penguins-lab-plot -b add-species-plot
Preparing worktree (new branch 'add-species-plot')
$ git worktree list
…/penguins-lab       a7004ec [main]
…/penguins-lab-plot  a7004ec [add-species-plot]
$ cd ../penguins-lab-plot
$ claude                        # this session lives on add-species-plot

add <path> -b <branch> creates the folder and a new branch in one step. list shows the main worktree first, then the linked ones, each with its branch.1 When you're done, git worktree remove ../penguins-lab-plot deletes the folder. "Only clean worktrees … can be removed" unless you add --force, and the main worktree can never be removed.1 Removing a worktree keeps its branch, so delete the branch separately.

A branch can be checked out in only one worktree at a time.1 If you try git switch add-species-plot in your main folder while the worktree has it, Git stops you: fatal: 'add-species-plot' is already used by worktree at '…/penguins-lab-plot'. That isn't a bug. It's the guarantee that keeps two sessions apart.

The Claude Code shortcut: claude -w

Claude Code can create the worktree for you. claude -w add-summary-stats (long form --worktree) makes the folder under .claude/worktrees/add-summary-stats/ "on a new branch named worktree-<name>", here worktree-add-summary-stats, and starts Claude inside it.2 Things to know:

• What it branches from. By default (worktree.baseRef: "fresh") it branches from the repository's default branch on the remote, usually main. Set it to "head" to branch from your current local HEAD instead.2
• Needs a commit. "The repository needs at least one commit first." In an empty repository the command fails.4
• Ignore the folder. "Add .claude/worktrees/ to your .gitignore." Otherwise worktree contents show up as untracked files in your main checkout.2
• Cleanup on exit. If the worktree has no changes, it is removed automatically. If it has changes or commits, Claude asks whether to keep or remove it, and "Removing deletes the worktree directory and its branch, along with all the work in them." Push your branch before you choose remove. Pick the session up again later with claude --worktree <name> --resume.2
• Mid-session. You can also just ask Claude to "work in a worktree."2 In a worktree session, Claude Code blocks edits to your main checkout.2

Data-science gotcha: every worktree needs its own environment

A worktree is a fresh checkout, so install dependencies there.2 Your .venv folder is gitignored, and virtual environments "should not be checked into source control" and are "disposable," so you recreate one rather than copying it.5 In each new worktree:

$ python -m venv .venv
$ source .venv/bin/activate        # Windows PowerShell: .venv\Scripts\Activate.ps1
$ pip install -r requirements.txt

Gitignored files such as .env (API keys, database URLs) aren't copied into a new worktree either. List them in a .worktreeinclude file (gitignore syntax) and claude -w copies them in for you.2

From two worktrees to two pull requests

Each worktree's branch is an ordinary feature branch. Push it, open its own pull request, and CI checks each one separately (lessons 4–5). Merge whichever finishes first. The second pull request may now be behind main. GitHub recommends merging the base branch into your topic branch frequently,6 so ask that session's Claude to merge main in and rerun pytest.

Cleanup after a squash merge: the branch's original commits never land on main, only the squashed copy does. So git branch -d add-species-plot refuses ("not fully merged"). Once you've confirmed the pull request merged on GitHub, git branch -D is safe.7

Do it for real

1. Land a quick PR that adds .claude/worktrees/ to .gitignore (the lesson 4 loop).
2. Terminal 1, in penguins-lab: run claude -w add-summary-stats. First ask it to set up .venv and install requirements.txt. Then: "Add summary_stats(df) returning mean bill length per species, with a test. Commit, push, and open a PR."
3. Terminal 2, also in penguins-lab: git worktree add ../penguins-lab-plot -b add-species-plot, then cd ../penguins-lab-plot. Create and activate a venv, run pip install -r requirements.txt, then start claude. Ask it for a plot_species(df) function, with the same commit, push, and PR instructions.
4. While both work, run git worktree list from your main folder. Then try git switch add-species-plot and read the refusal.
5. Watch both PRs' checks (gh pr checks --watch in each folder). Squash-merge the first one that's green.
6. In the other session: "Merge origin/main into this branch, rerun pytest, push." Merge it once CI is green. Lesson 11 explains why this step matters.
7. Clean up. Exit Terminal 1's Claude and choose remove (the branch is already merged). Then git worktree remove ../penguins-lab-plot and git branch -D add-species-plot, and in penguins-lab run git switch main and git pull.

Check yourself

Command drills