Lab 3.5: Multi-Claude Workflows

Module: 3.5 - Multi-Claude Workflows | ← SlidesDuration: 30 minutes Sample Project: hackathon-starter

Learning Objectives

By the end of this lab, you will be able to:

• Use Plan Mode to explore a legacy codebase without burning implementation context
• Hand off exploration results (SUMMARY.md) to a fresh Builder session
• Run parallel sessions with claude -w for independent tasks
• Choose the right multi-session pattern based on task characteristics

Prerequisites

• Completed previous Day 3 labs
• Familiarity with /rename, --resume, --continue (from Module 3.0)
• Ability to open two terminal windows
• Familiarity with the hackathon-starter project

Why Multi-Session?

The real reason isn't "multiple perspectives" — it's context management.

Context quality degrades as it fills. Will Ness documented this empirically:

• 0-40% full: high quality reasoning
• 40-70% full: medium quality
• 70%+ full: noticeably degraded

Exploring a legacy codebase burns context fast. By the time you've traced an auth flow through six files, your context is already half-gone before you've written a line. Separate sessions give each role a clean slate.

That said, be honest about when you need this:

Situation	Recommendation
Quick fix, known location	One session
Clear scope + good tests	Build + "review your work" in same session
Long exploration (50+ file reads)	Explore → Plan → Build
Independent parallel tasks	claude -w worktrees
Complex debugging, unknown root cause	Competing hypotheses (Agent Teams)
Security-sensitive changes	Fresh-context review

Most daily work doesn't need multi-session. Reserve it for when it earns its overhead.

---

Setup

cd sample-projects/hackathon-starter
# You'll need TWO terminal windows for this lab

---

Task 1: Explore → Plan → Build

Time: 15 minutes

This is the core pattern for legacy work. An Explorer maps the territory with full context. A Builder works from the map, never burning context on archaeology.

Step 1: Start the Explorer (Terminal A)

Open Terminal A and navigate to the project:

cd sample-projects/hackathon-starter
claude

Once Claude starts, name the session immediately:

/rename explore-lab35

Enter Plan Mode by pressing Shift+Tab twice (cycles: Normal → Auto-Accept → Plan Mode). You'll see the mode indicator change. Plan Mode prevents accidental edits while exploring.

Alternatively, start with the flag:

claude --permission-mode plan

Step 2: Give the Explorer its task

Trace the authentication flow in this application. Start from the route handler
for login. Map every file involved: controllers, models, middleware, config.
Note the patterns used (callbacks, promises, passport strategies). Save your
findings to SUMMARY.md. Do not modify any source files.

Wait for the Explorer to finish and produce SUMMARY.md.

Step 3: Review the summary

Open SUMMARY.md and read it before continuing. Ask yourself:

• What files are involved in auth?
• What patterns does the codebase use (callbacks, promises, passport strategies)?
• Any middleware or config you didn't expect?

The summary is the handoff artifact. If it's vague, ask the Explorer to be more specific before moving on.

Step 4: Start the Builder (Terminal B)

Open Terminal B. Start a fresh Claude session:

cd sample-projects/hackathon-starter
claude

Name it immediately:

/rename build-lab35

Step 5: Give the Builder its task

Read SUMMARY.md. Add rate limiting to the login endpoint — max 5 attempts per
IP per 15 minutes. Follow the patterns documented in the summary. Write tests
that match the existing test style.

The Builder works from the Explorer's map. It never has to re-read the files the Explorer already traced — that context is preserved in SUMMARY.md.

Success criteria:

• [ ] Explorer produced a SUMMARY.md with a file map and patterns
• [ ] Builder worked from SUMMARY.md without re-reading files the Explorer already mapped
• [ ] Builder followed the patterns documented in the summary
• [ ] Tests pass

---

Task 2: Parallel Worktrees with claude -w

Time: 10 minutes

claude -w creates an isolated worktree for each session. Both run in parallel with no risk of conflicts.

Step 1: Start two worktrees

Open two terminals and run these simultaneously:

Terminal A:

cd sample-projects/hackathon-starter
claude -w task-a

Give it this task:

Add input validation to the signup form in controllers/user.js. Validate email
format and password strength (minimum 8 characters, at least one number).

Terminal B:

cd sample-projects/hackathon-starter
claude -w task-b

Give it this task:

Write unit tests for the user profile update functionality. Focus on edge cases:
missing fields, invalid email format, duplicate usernames.

Step 2: Observe the isolation

While both sessions run, check what claude -w created:

ls .claude/worktrees/
git worktree list

Each session has its own directory and branch (worktree-task-a, worktree-task-b). They can't accidentally edit each other's files.

Step 3: Exit one with no changes

Exit one of the sessions without making any changes. The worktree and branch are cleaned up automatically. If changes exist, Claude prompts you to keep or remove.

Success criteria:

• [ ] Each worktree has its own branch
• [ ] Both tasks completed without conflicts
• [ ] Automatic cleanup worked on exit

---

Choosing Your Approach

Approach	When to use	Coordination
Single session	Sequential tasks, simple changes	None needed
Explore → Plan → Build	Long exploration, legacy archaeology	SUMMARY.md handoff
claude -w	Independent parallel tasks	Automatic cleanup
Subagents (Module 3.2)	Focused tasks where only the result matters	Automatic
Agent Teams (experimental)	Complex parallel work, hard debugging	Automated task list

Start simple. Escalate when context, parallelism, or risk demands it.

---

Tips for Success

1. Name sessions immediately — /rename explore-lab35 before you do anything else
2. Resume by name — claude --resume explore-lab35 picks up exactly where you left off
3. Fork a session — claude --resume explore-lab35 --fork-session creates a new session from an existing one, useful for branching off an exploration
4. Clear between phases — /clear if you're staying in the same session but switching roles
5. Use worktrees for parallel work — claude -w handles isolation and cleanup automatically
6. Plan Mode for exploration — Shift+Tab twice, or --permission-mode plan, prevents accidental edits while mapping
7. Commit SUMMARY.md — it's not throwaway. It's your documentation.

---

Worktrees for Parallel Work

For larger parallel efforts, worktrees give each Claude its own isolated directory.

Built-in worktrees (recommended)

Use the --worktree (-w) flag — Claude creates and manages the worktree for you:

# Terminal 1: Explorer Claude in its own worktree
claude -w explorer-lab35
# Creates .claude/worktrees/explorer-lab35/ with branch worktree-explorer-lab35

# Terminal 2: Builder Claude in its own worktree
claude -w builder-lab35
# Creates .claude/worktrees/builder-lab35/ with branch worktree-builder-lab35

# Omit the name for an auto-generated one
claude -w
# Creates something like .claude/worktrees/bright-running-fox/

Cleanup is automatic: if you made no changes, the worktree and branch are removed on exit. If changes exist, Claude prompts you to keep or remove.

Tip: add .claude/worktrees/ to your .gitignore.

Manual worktrees (for more control)

When you need a specific branch or a custom location, create worktrees with Git directly:

# Create worktrees for parallel work
git worktree add -b explore ../hackathon-explore
git worktree add -b build   ../hackathon-build

# Terminal 1: Explorer Claude
cd ../hackathon-explore && claude

# Terminal 2: Builder Claude
cd ../hackathon-build && claude

# Check your worktrees
git worktree list

# Clean up when done
git worktree remove ../hackathon-explore
git worktree remove ../hackathon-build

Remember: each worktree may need its own dependency install (npm install, etc.).

---

Troubleshooting

Sessions conflicting on the same files:

• Work on different files, or use claude -w for isolation

Context confusion between sessions:

• Each session is independent — share context explicitly via @file references or copy-paste

Too many sessions open:

• Start with 2, add more only if needed. More isn't always better.

Plan Mode not activating:

• Press Shift+Tab twice from the default mode (Normal → Auto-Accept → Plan Mode)
• Or start with claude --permission-mode plan

Worktree already exists error:

• Run git worktree list to see what's there, then git worktree remove <path> to clean up

---

Stretch Goals

1. Try Agent Teams — Enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, then try:

   Create an agent team to investigate a bug from three angles: one teammate
   on security, one on performance, one on test coverage. Require plan approval
   before any changes.

   Use claude --teammate-mode in-process to keep all teammates in one terminal (Shift+Down to cycle), or --teammate-mode tmux for split panes.

   Known limitation: /resume does not restore in-process teammates. If you resume a session, the lead may try to message teammates that no longer exist — tell it to spawn new ones.

2. Add subagent worktree isolation — revisit Module 3.2 and add isolation: worktree to a subagent's frontmatter. The worktree is auto-cleaned when the subagent finishes without changes.

3. Preview headless mode — use claude -p as a CI review step (covered fully in Module 3.6):

   claude -p "Review the diff in SUMMARY.md and flag any security concerns."

---

Deliverables

At the end of this lab, you should have:

1. A SUMMARY.md file produced by the Explorer
2. Code changes implemented by the Builder working from SUMMARY.md
3. Experience with claude -w parallel worktrees
4. A clear sense of when each pattern is worth the overhead

---

Next Steps

After completing this lab, move on to Lab 3.6: CI/CD & Headless Mode.