7.4 Parallel Sessions with Git Worktrees

Course: Claude Code - Power User Section: Session Management Video Length: 2-5 minutes Presenter: Daniel Treasure

Opening Hook

Run multiple Claude Code sessions simultaneously on different branches. Git worktrees let you work on features in parallel without file conflicts or context thrashing.

Key Talking Points

1. What Are Git Worktrees?

Git worktrees allow multiple working directories from a single repository
Each worktree exists in a separate directory on a separate branch
Prevents file conflicts when working on different features simultaneously
Each worktree can run its own independent Claude Code session

What to say: "Imagine having two complete copies of your project on different branches, in different folders, with independent Claude sessions running in each. That's git worktrees. No context switching, no file collisions."

What to show on screen: Show a filesystem with multiple directories representing the same repo. Highlight that each has its own branch checked out. Show multiple Claude Code windows open side-by-side.

2. Creating a Worktree

Use git worktree add <path> <branch>
Syntax: git worktree add ../feature-auth feature-auth
Creates new directory with the branch checked out
Safe to modify files in each independently

What to say: "Creating a worktree takes one command. You pick a path, pick a branch, and git handles the rest. You instantly have a second copy without duplicating the entire repo."

What to show on screen: Show the git command being executed. Point out the new directory appearing in the file system. Explain that it's a real checkout of the branch, not a copy.

3. Running Claude in Each Worktree

cd ../feature-auth && claude starts a session in that worktree
Each instance of Claude Code runs independently
Separate conversation history per worktree
No context bleeding between sessions

What to say: "Once you're in the worktree, just start Claude normally. It has no idea this is a worktree—to Claude, it's just a project folder."

What to show on screen: Show navigating into the new worktree directory with cd. Then type claude to start a new session. Show Claude opening with fresh context, unaware of the other session.

4. Parallel Workflows with Multiple Sessions

Work on feature-auth in one terminal/window
Work on feature-database in another terminal/window
Switch between terminals without stopping Claude sessions
Merge branches normally when ready

What to say: "You can truly multi-task now. Have Claude working on API endpoints in one session, working on database schema in another—totally independent, zero context loss."

What to show on screen: Demonstrate having two terminal windows open (split screen if possible). Show claude running in each, with different conversations. Switch between them to show they're running independently.

5. Adding Directories to Sessions

Use --add-dir flag to expand a session beyond one worktree
Useful when you need multiple related directories
Syntax: claude --add-dir /path/to/other/directory
Allows Claude to see and modify code across multiple worktrees

What to say: "Sometimes you need to coordinate across worktrees. The --add-dir flag lets you expand a single Claude session to work with multiple directories without losing independence."

What to show on screen: Show the --add-dir flag in action. Create a session and add a second directory to it. Show Claude being able to reference and modify files in both.

6. Merging and Cleanup

Work independently on each worktree
Push branches, open PRs normally
git worktree remove <path> deletes the worktree
Main repo stays clean

What to say: "When you're done, merge like normal. Worktrees are temporary—delete them once the feature is merged and you're back to a single clean directory."

What to show on screen: Demonstrate merging a branch and then running git worktree remove on the corresponding worktree. Show the directory disappearing.

Demo Plan

Start with a main repo (30 seconds) — Show a project in the main directory with git status showing main branch.
Create a worktree (45 seconds) — Type git worktree add ../feature-auth feature-auth. Show the new directory appearing. Verify the branch is correct with git branch.
Start Claude in main repo (1 minute) — Open Claude Code in the main directory. Start a conversation about a task (e.g., "add email validation").
Start Claude in worktree (1 minute) — Open a second terminal, cd into the feature-auth worktree, and run claude. Show a separate conversation starting.
Demonstrate parallel work (1 minute) — Show both Claude instances working independently. Switch between terminals to demonstrate they're running concurrently without interference.
Show cleanup (30 seconds) — Return to main repo, demonstrate merging a feature branch, then remove the worktree with git worktree remove.

Code Examples & Commands

Create a New Worktree

git worktree add ../feature-auth feature-auth
cd ../feature-auth

Start Claude in Worktree

cd ../feature-auth
claude

List All Worktrees

git worktree list

Example Output

/home/user/myapp             a1b2c3d [main]
/home/user/feature-auth      d4e5f6g [feature-auth]
/home/user/feature-database  h7i8j9k [feature-database]

Add Additional Directory to Session

claude --add-dir /home/user/shared-config

Remove a Worktree After Merging

cd /home/user/myapp
git worktree remove ../feature-auth

Prune Worktrees After Deletion

git worktree prune

Gotchas & Tips

Worktrees share .git but not working files — The .git directory is shared across all worktrees (pointing to the main repo), but each has its own checked-out files. Modifications are isolated.
Branches must be unique per worktree — You cannot have the same branch checked out in two worktrees simultaneously. Each worktree needs its own branch.
Stashing doesn't sync between worktrees — If you stash changes in one worktree, they won't appear in another. Each has its own working directory.
Main directory cannot be deleted while worktrees exist — The main worktree (where .git lives) cannot be removed with git worktree remove. Delete feature branches first.
Claude context is fully independent — Each Claude session maintains its own conversation history and context. There's no automatic sync between them (unless you use --add-dir).
Use descriptive worktree names — Since paths become part of your workflow, use clear names like feature-auth, bugfix-payments, not test or tmp.
Consider using tmux or screen for multiple terminals — Managing multiple terminal windows can be cumbersome. Terminal multiplexers like tmux let you split and organize them elegantly.

Lead-out

You've now mastered session management—from project memory, to continuing sessions, to checkpointing, and finally parallel work with git worktrees. These tools combine to give you unprecedented control and flexibility in your Claude Code workflow.

Reference URLs

Git worktrees official documentation: https://git-scm.com/docs/git-worktree
Pro Git book on branching: https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging
tmux guide for terminal multiplexing: https://github.com/tmux/tmux/wiki
GNU Screen documentation: https://www.gnu.org/software/screen/

Prep Reading

Understand your branching strategy (GitFlow, trunk-based, etc.)
Review how your team uses feature branches
Consider your typical parallel workload (how many features at once?)
Explore terminal multiplexers if managing multiple windows appeals to you

Notes for Daniel: This is the capstone of the session management section. Emphasize the freedom it provides—developers can truly multi-task without context loss. Show the side-by-side workflow prominently. This feature appeals especially to developers juggling multiple features or bugs. Keep the technical details about .git sharing simple; most developers just need to know "each worktree is independent" without diving into git internals. End with excitement about having covered the full session management toolkit.

Quick Reference