Video 22.2: Running Parallel Claude Sessions

Course: Claude Code - Parallel Agent Development (Course 4) Section: S22 - Git Worktrees and Manual Patterns Video Length: 4-5 minutes Presenter: Daniel Treasure

Opening Hook

Now that you know how worktrees work, let's actually use them. The power of parallel AI development is running multiple Claude Code sessions simultaneously, each in its own worktree, each working on a different task. In this video, we'll set up two parallel Claude sessions using tmux and show you how to assign and coordinate work between them.

Key Talking Points

What to Say: The Parallel Agent Pattern

One agent per worktree: Each Claude Code session should run in its own worktree directory. They're completely independent and can work at full speed without stepping on each other's files.
You are the orchestrator: Unlike tools that automatically coordinate agents (we'll see those later), the manual pattern is straightforward: you decide who does what. Agent A modifies backend services, Agent B handles frontend. You keep track of the split.
tmux for visibility: tmux lets you split your terminal into panes, each running a Claude session in a different worktree. You can see both working in real time and switch between them instantly.
No automatic coordination overhead: Agents don't wait for each other, don't communicate, don't negotiate locks. They just work. If you designed the task split well, they never conflict.
Coordination is simple: You write a task assignment — "Agent A, implement User service in services/user.ts. Agent B, create the database schema in schema/users.sql." They each see the same codebase, work in parallel, and commit independently.
Real production example: incident.io used exactly this approach — isolated worktrees, focused agent tasks, successful deployment. No complex orchestration needed.

What to Show on Screen: Setting Up the Sessions

Start with a repository and 2-3 worktrees already created
Open tmux and split the window into two panes
In pane 1: navigate to worktree-A and start Claude Code
In pane 2: navigate to worktree-B and start Claude Code
Show both sessions running simultaneously, showing how you can see both agents' activity
Demonstrate switching focus between panes and assigning different tasks to each agent
Show the task assignment as natural conversation, not formal API calls
Demonstrate that changes made in one worktree don't appear in the other (proving isolation)

Demo Plan

Timing: ~2.5 minutes for demo

Step 1: Verify Worktrees Are Ready (30 seconds)

From the main directory, run: git worktree list
Confirm you have at least 2 worktrees set up (e.g., main, auth-worktree, database-worktree)
Show the directory structure: ls -la to see the sibling worktree directories

Step 2: Open tmux and Set Up First Pane (45 seconds)

Launch tmux if not already running: tmux new-session -s parallel
You're now in one pane (pane 0)
Navigate to the first worktree: cd ../auth-worktree (or whichever you prepared)
Verify you're in the right place: pwd and git branch
Start Claude Code: claude-code or claude (depending on installation)
Once Claude opens, give it a simple task prompt to establish connection (e.g., "List the files in the src directory")

Step 3: Split tmux and Set Up Second Pane (45 seconds)

In tmux, split vertically: Ctrl+B, then %
You now have two panes side by side
In the new pane (right side), navigate to the second worktree: cd ../database-worktree
Verify: pwd and git branch
Start Claude Code in this pane too: claude-code
Give it a task prompt (e.g., "Show me the schema files")

Step 4: Demonstrate Independent Work (45 seconds)

In pane 1 (auth): Ask Claude to create a new file services/auth.ts with a simple Auth service class
Watch it work and complete
Switch to pane 2 (database): Ask Claude to create a new file schema/users.sql with a user table
Watch it complete independently
Show both working in parallel (you can see both terminal outputs)

Step 5: Verify Isolation (45 seconds)

In pane 1, run: ls -la services/ — you'll see auth.ts exists
Switch to pane 2: ls -la services/ — no auth.ts here (it only exists in the auth-worktree)
In pane 2, run: ls -la schema/ — you'll see users.sql exists
Switch to pane 1: ls -la schema/ — doesn't exist here
This proves complete isolation: each worktree has its own file state

Step 6: Show Task Assignment Pattern (30 seconds)

In pane 1, tell Claude: "You are the auth agent. Your job is to implement authentication services in the services/ directory. Do not touch database files."
In pane 2, tell Claude: "You are the database agent. Your job is to design and implement the database schema in the schema/ directory. Do not touch service files."
Show how each agent acknowledges their role and focuses on their assigned area
This is the manual coordination pattern — you set boundaries, they respect them

Code Examples & Commands

tmux Session Management

# Create a new tmux session named "parallel"
tmux new-session -s parallel

# Split pane vertically (create a new pane on the right)
# Inside tmux: Ctrl+B then %

# Split pane horizontally (create a new pane below)
# Inside tmux: Ctrl+B then "

# Navigate between panes
# Inside tmux: Ctrl+B then arrow keys (←, →, ↑, ↓)

# Kill a pane
# Inside tmux: Ctrl+B then X (then confirm)

# Kill the entire session from within
# Inside tmux: Ctrl+B then D (detach and leave it running)

# List running tmux sessions
tmux list-sessions

# Attach to an existing session
tmux attach-session -t parallel

Launching Claude Code

# Standard Claude Code launch (opens in default browser)
claude-code

# Launch with specific project directory
cd /path/to/worktree && claude-code

# Launch with project flag (if your Claude Code version supports it)
claude-code --project /path/to/worktree

Verifying Worktree State

# Check current worktree path
pwd

# Check current branch
git branch

# Confirm files are isolated
ls -la src/
cat src/specific-file.ts

# See what's changed in this worktree
git status

# Show commits in this worktree (same history, different working state)
git log --oneline -5

Simple Task Assignment Prompts

# In pane 1 (auth agent):
"You are the authentication agent. Implement a UserService class in services/user-service.ts
with methods: login(email, password), register(email, password), logout(). Use TypeScript."

# In pane 2 (database agent):
"You are the database schema agent. Create a users table in schema/users.sql with columns:
id (primary key), email (unique), password_hash, created_at, updated_at."

Gotchas & Tips

Common Pitfalls

Both agents touching the same file: If you assign overlapping work (both editing src/index.ts), you'll get merge conflicts. The task split is critical. Make it clear and distinct.
Forgetting which pane is which: Easy to lose track of which tmux pane is which worktree. Add clear prompts or labels (e.g., "Agent A (Auth)" in the pane header).
Claude Code connections: Each session runs independently, but they're all connecting to the same Claude API. No quota issues, but be aware if you're running lots of agents that costs add up.
Git state confusion: Running git status, git log, or git diff in the wrong pane is disorienting. Always verify your path and branch first.

Pro Tips

Label your panes: Use a simple script or tmux config to show which worktree/agent is in each pane. Helps prevent mistakes.
Keep task descriptions simple and clear: "You modify files in src/services/. You do not modify schema/ or tests/." is much clearer than vague instructions.
Monitor both sessions passively: Don't interrupt agents while they're thinking. Let them work, watch the output, and only step in if needed.
Use pane zooming for detail: In tmux, Ctrl+B then Z zooms a pane to full screen. Useful for reviewing output. Ctrl+B then Z again unzooms.
Save session state: If your tmux session is productive, you can detach (Ctrl+B then D) and reattach later with tmux attach-session -t parallel.

Task Assignment Best Practices

Divide by module/directory: Agent A owns src/services/, Agent B owns src/schema/, etc.
Avoid overlapping concerns: Don't have both agents implementing the same feature. Each agent should own complete, vertical slices of functionality.
Write files to different locations: If both agents write, ensure they write to completely separate file paths.
Use clear naming: services/auth.ts vs schema/auth.sql makes it obvious these are separate concerns.

Lead-out

At this point, you have two Claude agents working independently in parallel. But what happens when they're done? How do you merge their work without conflicts? That's where merge strategies come in. In the next video, we'll explore how to prevent and resolve merge conflicts, and we'll introduce the clash tool for early conflict detection.

Reference URLs

tmux Manual
tmux Cheat Sheet
Claude Code Documentation
incident.io Case Study (or general parallel development posts)

Prep Reading

Review tmux basics (pane splitting, navigation) — 5 min
Set up 2-3 worktrees on your demo repo before recording
Prepare a simple project (even a basic Node.js or Python project) with a few initial files so agents have something to build on
Test that Claude Code launches cleanly in both worktrees

Notes for Daniel

This video is about making the manual pattern feel natural and understandable. The key insight is: you (the presenter/orchestrator) decide what each agent does, and worktrees + tmux make it easy to see and manage. Don't overcomplicate it.

The tmux splits should feel smooth and intentional. Practice the split, navigation, and launching Claude Code in each pane a few times beforehand so it flows naturally on camera.

When showing isolation, make it obvious and satisfying: "Notice how auth.ts only exists in this worktree, not in the other one. That's the isolation we built with Git worktrees." Viewers should feel the power of independent work happening simultaneously.

The task assignment is conversational. Don't treat it like a formal API call or a config file. You're just telling Claude what to focus on: "You're the auth agent, work on auth." Simple and natural.

Optional: Show a quick diagram or text overlay showing the architecture: Main .git + Worktree A (Claude Session 1) + Worktree B (Claude Session 2), all visible in tmux panes. Helps viewers remember the setup.

Quick Reference