Specialist, optional. Once you have a working Context Engineering for Claude Code project, some of what's left to build genuinely doesn't depend on the rest. This module is for running two agents on two of those pieces at once, without either one blocking the other or quietly overwriting its work.
You end with two pieces of real work landed on main, each built in its own worktree, and an integration review that checked them together, not just apart.
The lessons
In order. Each one answers a specific way parallel work goes wrong.
Why a branch alone blocks main
One working copy can only be checked out to one branch at a time. A second agent who wants to start something else has to wait, stash, or step on the first agent's half-finished change.
The Claude Code worktree layout
One folder per feature, each checked out to its own branch, sitting beside the main folder — not inside it. Main stays on main the whole time.
Naming: dev-doc, worktree, branch
The three names should be traceable to each other, so anyone can find the dev-doc from the branch or the worktree from either. The exact naming recipe is part of the work-record skill and isn't published here — keep your own three consistent and it works.
Splitting work that is genuinely independent
Two units of work are safe to parallelise only if neither one's outcome changes what the other should do. Overlapping edits to the same file are a warning sign, not an automatic blocker — it depends on what kind of edit.
Model roles
Opus scopes each worktree's piece of work before it starts. Sonnet does the building, one per worktree. Fable reviews the merged result — a model that didn't write either branch, checking both at once.
Integration review
Two branches with no git conflicts can still be wrong together. The integration review opens the merged files, not the two diffs separately.
The assignment
The core project, with two competitors still to add. On your own project, that's whatever two units of work you can genuinely run side by side — see splitting work that's genuinely independent below.
Two competitors added in two worktrees, merged, reviewed.
Both land on main without overwriting each other, and the integration review names at least one thing that had to be reconciled.
Why a branch alone blocks main
One working copy can only be checked out to one branch at a time. That's fine for one agent. It stops being fine the moment a second one wants to start.
- —
Agent A checks out feat/add-search and starts editing.
- —
Agent B wants to start fix-checkout-bug in the same folder.
- —
Checking out main now would discard A's half-finished change, or force a stash A has to remember to restore.
- —
B waits, or the two agents take turns.
- —
Main folder stays checked out to main, untouched.
- —
Agent A works in example-app-workstreams/add-search.
- —
Agent B works in example-app-workstreams/fix-checkout-bug at the same time.
- —
Neither folder's state affects the other. Nobody waits.
The Claude Code worktree layout
Demonstrated on a dummy project, not a real one. Main always stays checked out in the project folder; every feature gets its own folder beside it, in a sibling *-workstreams/ directory.
~/projects/
├── example-app/ # main is always checked out here
└── example-app-workstreams/
├── add-search/ # one worktree per feature
└── fix-checkout-bug/The exact commands — add a worktree, work in it, remove it once the branch is merged.
# from inside example-app, on main
git worktree add ../example-app-workstreams/add-search -b feat/add-search
# work happens in the new folder — main is untouched
cd ../example-app-workstreams/add-search
# ...build, commit, push, open the PR from here...
# once the branch is merged, remove the worktree
cd ../../example-app
git worktree remove ../example-app-workstreams/add-searchClaude Code's own built-in worktrees (.claude/worktrees/, inside the project) are for a throwaway experiment you'll discard either way. Real feature work gets a named worktree in the sibling *-workstreams/ folder above, where it survives review and merge like any other branch.
Splitting work that's genuinely independent
More worktrees isn't automatically more speed. Two units of work are only safe to parallelise if neither one's outcome changes what the other should do.
Give one worktree everything Core 2 touches and the other everything Core 3 touches — more surface, more parallel work done at once.
Would you approve this?
We would reject it.
Not actually independentBoth would edit the same CLAUDE.md and the same dev-docs/ folder as the project moves forward, so the split isn't actually independent — it's the same files, just at different times. The two agents can't see each other's in-progress decisions, so they'll make inconsistent calls on the same open questions and one merge will have to unpick the other's assumptions. Split on the thing that doesn't need the other's outcome to know what to do — here, that's one competitor per worktree, each adding its own row to data.js.
Model roles
The same three roles as the rest of the course, applied per worktree instead of per session.
Opus
Scopes each worktree's piece of work before either one starts — this is what makes the split in the section above something you decided, not something that just happened.
Sonnet
Builds — one Sonnet per worktree, working from that worktree's own scope only.
Fable
Reviews the merged result — a model that wrote neither branch, checking both at once. That's the integration review, next.
Integration review
Two branches with no git conflicts can still be wrong together. Would you approve this?
Both branches merge with no git conflicts reported. Ship it.
Would you approve this?
We would reject it.
No integration readGit only checks whether the same lines changed. Both worktrees added a competitor by appending a row to data.js — no line overlap, so the merge is clean by git's definition. But each worktree's agent assumed it was adding the sixth row, and the page that reads data.js assumed exactly five. The merge is clean and the page is still wrong, and nothing in either diff shows it — only opening the merged page does. That's what an integration review is for: it reads the merged files, not the two diffs on their own.
Give two pieces of work their own space
One command sets up a separate work area per feature so neither blocks the other, and one prompt reviews the two once they are back together.
The setup script and the integration review prompt
One command gives a piece of work its own area so it never blocks the other, and one prompt checks the two once they are back together.
One folder, one branchBoth jobs share the same folder, so the second one waits for the first to finish before it can even start.
Switching between them mid-flight leaves half-finished files behind and loses the thread.
One folder per piece of workA separate work area per feature
Main stays checked out and clean
- Setup
- git worktree add ../worktrees/add-competitor -b feat/add-competitor — one command, its own folder, its own branch.
- Why it frees you
- Each job has its own files on disk, so two can run at the same time without blocking or overwriting each other.
- Finishing
- git worktree remove ../worktrees/add-competitor once it is merged, so old work areas do not pile up.
- The catch
- Git merging cleanly is not the same as the two changes fitting together. The integration review prompt is what checks that.
FAQ
Related reading: Move from idea to evidence shares the research-to-build route two parallel worktrees each still have to follow, and the Claude Agents toolkit covers running several agents on one project beyond just worktrees. Automate recurring work is what each worktree's Sonnet is usually running once it's a repeated procedure, and Run research you can trace is the specialist most worth pairing with a worktree per source.
Want your team actually running two agents at once?
A working session on splitting real work, wiring up worktrees, and reviewing what comes back.
The course
Core modules first. Specialists are optional — take the one that matches your work.
- Core 1
Stop Claude guessing
Turn a vague idea into a brief Claude can build from: facts, assumptions marked as assumptions, agreed success criteria.
- Core 2
Stop starting over
Set up project memory so a fresh session, or a teammate, can pick the work up from the files alone.
- Core 3
Move from idea to evidence
The route from brief to reviewed change: research, one shared page, a prototype, a plan, a small build, a second opinion.
- Specialist 4
Automate recurring work
Encode a procedure you repeat as a skill, and fire it automatically with a hook.
- Specialist 5
Build in parallel
Run two pieces of work at once without them blocking each other, then review how they fit together.
You are here - Specialist 6
Run research you can trace
Research where every claim traces back to a saved source, and gaps are marked instead of filled in.
- Standalone
MCP or a single API call
A judgment call on two axes: what it costs you in context window, and how much access it opens.
Behrad Mirafshar
Founder, Bonanza Design
Founder of Bonanza Design. Builds operating brains for companies in the AI knowledge crisis. Multi-week engagements, run on the client's infrastructure, owned by the client.
Connect on LinkedIn