Claude Code Parallel Agents: Ship 10x Faster With Worktrees

Last Tuesday I ran claude code parallel agents for the first time and refactored 14 files in 8 minutes.

Not 14 files in 8 minutes of my time, with some agent doing the heavy lifting while I sipped coffee. I mean 14 files edited, tested, and committed across 4 separate branches in the wall-clock span it takes me to make a pour-over. I was watching four agents work at once, each in its own little room of the codebase, none of them stepping on each other's toes. When they were done, I merged three branches cleanly and manually resolved one conflict in about ninety seconds.

The feature is Anthropic's worktree-based multi-agent system, announced by Boris Cherny in February 2026. And it broke my brain a little.

Here is what I used to do. I'd ask Claude Code to rename a function across a codebase. It would grep, edit, grep, edit, grep, edit. Sequential. Honest work. But if I also wanted to extract a module, update the tests, and refactor the config loader, I had to either stack those asks into one long session (and pray the context window held) or run them one after another. The bottleneck was never the model. It was me, standing in a doorway, only letting one crew through at a time.

Worktrees fix that. And once you see it, you can't unsee it.

I am going to walk through the mental model, the setup, a real 4-agent refactor I ran last week, how the branches come back together, and the four ways I've watched it break. If you just want the vibe: think construction crew, not assembly line.

The mental model: four crews, four rooms

Imagine you're renovating a house. You have one contractor. He's good. But he can only work on one room at a time. Kitchen Monday, bathroom Tuesday, bedroom Wednesday. You are paying for his skill, but you're also paying for his sequentialness. The house is a single-threaded program.

Now imagine you hire four crews. One does the kitchen. One does the bathroom. One does the bedroom. One does the hallway. They never walk into each other's rooms. At the end of the week, you walk through the house and approve everything. The total labor didn't change. The elapsed time collapsed.

That is what a git worktree does to your repo. And claude code parallel agents is the software that hires the crews, briefs them, and walks the rooms with you at the end.

A git worktree is an extra working directory that shares the same .git object store as your main repo but checks out a different branch into a different folder. Same history, same commits, different physical workspace. You've always been able to do this manually: git worktree add ../project-feature-x -b feature/x, and now you have a second folder where you can edit, build, and test in parallel without disturbing your main checkout.

Claude Code's parallel agents feature wraps that primitive. You describe a set of tasks. Claude spawns N background sessions, each in its own worktree, each on its own branch. Each agent has its own context window, its own plan, its own file locks. They don't share scratchpads. They don't compete for the cursor. They work in parallel, and they report back when they're done.

The crucial thing to internalize is that they are not threads of one brain. They are four separate brains in four separate rooms, each with the same blueprints (your CLAUDE.md, your rules files, your repo history) but operating independently. If crew two discovers the floorboards are rotten, crew three doesn't automatically know. That independence is the source of the speedup and also the source of every failure mode I'll get to later.

Setup: the five-minute version

You need Claude Code at version 2.x or newer and a repo that's actually a git repo. That's it. Parallel agents ship in the CLI, Desktop, IDE, web, and mobile clients, so pick your surface.

Start with the CLI because it's the most transparent about what's happening under the hood.

# make sure you're current
claude --version
# 2.4.0 or newer
 
# inside your repo
cd ~/code/my-app
claude

Once the session opens, you kick off a parallel run with the /parallel command. You can also invoke it by just describing a task that looks fan-out-able, and Claude will ask if you want to run it with parallel agents. I prefer being explicit.

> /parallel
How many agents? 4
Describe the task for each agent (or give me one task and I'll split it).

Behind the scenes, Claude Code is running something like this for each agent:

git worktree add ../my-app-agent-1 -b claude/agent-1-refactor-auth
git worktree add ../my-app-agent-2 -b claude/agent-2-update-tests
git worktree add ../my-app-agent-3 -b claude/agent-3-extract-module
git worktree add ../my-app-agent-4 -b claude/agent-4-fix-types

Each worktree gets its own folder next to your repo. Your main checkout stays untouched. You can see them with git worktree list.

Before you run anything real, do three small things:

1. Check your CLAUDE.md is in order. All four agents will read it. If your rules are messy, you get four messy agents instead of one. Our CLAUDE.md rules files definitive guide goes deep on this.
2. Make sure your .gitignore is honest. The worktrees share it. If you've been sloppy about ignoring node_modules or .env.local, you'll notice fast.
3. Commit or stash anything dirty in your main checkout. Worktrees can't be created against a branch that's already checked out elsewhere, and you don't want surprises.

That's the whole setup. No config file, no MCP server, no new subscription tier. Just git doing what git has quietly been able to do since 2015, wrapped in a thing that finally makes it useful for the rest of us.

Real example: the 4-agent refactor that changed my mind

Here is the actual task I ran last Tuesday. The context: a Next.js app with a legacy utils/ folder that had grown into a 3,400-line grab bag. I wanted to split it into four focused modules: auth, format, db, and validation. Each split needed the module extracted, the imports updated across the codebase, the tests reorganized, and the type definitions tightened.

Classic serial task. Classic candidate for parallelism.

I opened Claude Code in the repo root and typed this:

> /parallel 4
 
Task: split utils/ into four modules. Each agent takes one module.
 
Agent 1: extract auth helpers from utils/ into lib/auth/.
  Update all imports. Move related tests to __tests__/auth/.
Agent 2: extract formatting helpers into lib/format/.
  Same pattern. Do not touch auth, db, or validation code.
Agent 3: extract db helpers into lib/db/.
  Same pattern. Preserve the existing connection pool singleton.
Agent 4: extract validation helpers into lib/validation/.
  Same pattern. Keep the zod schema re-exports working.
 
Constraints: do not edit files outside your module. Do not modify
package.json. If you hit a shared helper, note it but leave it in utils/
for the merge pass. Commit with message "refactor(<module>): extract
from utils".

Claude confirmed the plan, spawned four background sessions, and I watched four status lines update in real time.

agent-1 (auth)       running  edited 4 files  tests: 12/12 pass
agent-2 (format)     running  edited 5 files  tests: 8/8 pass
agent-3 (db)         running  edited 3 files  tests: 6/6 pass
agent-4 (validation) running  edited 2 files  tests: 4/4 pass

Eight minutes later, three were green and one was yellow. Agent 3 (db) flagged that a helper called withTransaction was used by both the db module and the auth module. It stopped, logged the question, and waited. That is exactly what I want a junior developer to do, and it is the behavior I've been trying to prompt Claude into for a year.

I answered: "Leave it in utils/ and both modules will import from there for now. We'll extract it in a follow-up." Agent 3 finished in another forty seconds.

Napkin math on what just happened. Serial, this is a 45 to 60 minute task for me at full focus. Four agents in parallel did the grunt work in 8 minutes of wall clock time. I spent maybe 6 minutes writing the prompt and 2 minutes answering the one question. Say 16 minutes total. That is a 3x to 4x speedup on this task, which is boring but important: the speedup isn't 10x across the board, it's 10x on the subset of tasks that are naturally fan-out-able.

Which, it turns out, is more of your work than you'd guess. Once you start looking for tasks that fan out cleanly, you see them everywhere: bumping a dependency across a monorepo, adding logging to every handler, translating copy into four locales, writing tests for four adjacent utility files, migrating a bunch of components to a new design token set. Anything where the work is wide rather than deep is a candidate.

Merge strategies: how the rooms become a house

You have four branches. Now what?

Claude Code gives you two paths: auto-merge for the non-conflicting changes, and manual merge for anything that touches overlapping files. In practice you use both. The tool shows you a diff preview for each branch and a conflict summary across all of them.

> /parallel merge
 
claude/agent-1-refactor-auth       clean    auto-merge? [Y/n]
claude/agent-2-update-tests        clean    auto-merge? [Y/n]
claude/agent-3-extract-module      1 file   manual review
claude/agent-4-fix-types           clean    auto-merge? [Y/n]

Auto-merge here is just git merge --no-ff under the hood, with the branch name preserved in the commit. It refuses to touch anything where two agents wrote to the same file. That refusal is the whole safety feature. It means you will never wake up to a silently-resolved merge conflict that broke something subtle.

For the one manual case (agent 3 had touched utils/index.ts that agent 1 also modified), Claude opened a side-by-side view, showed me both hunks, and offered three resolutions: take left, take right, take both. I picked "take both" because the edits were at different lines, verified the result, ran the tests, and committed.

After merging, I cleaned up. You can do it by hand:

git worktree remove ../my-app-agent-1
git worktree remove ../my-app-agent-2
git worktree remove ../my-app-agent-3
git worktree remove ../my-app-agent-4
git branch -d claude/agent-1-refactor-auth
# ...etc

Or, easier, /parallel cleanup from inside Claude and it prunes the worktrees and deletes the merged branches. I've made a habit of always reviewing git worktree list afterward, because orphan worktrees are annoying to notice later.

One merge pattern I've grown fond of: stacked merges. Instead of merging all four into main, I'll merge them into a single integration branch first, run the full test suite there, then merge the integration branch to main as a single commit. This gives me one reviewable PR instead of four, which my teammates appreciate. The GitHub discussion on worktree-based workflows has a few variations worth reading if you care about this.

When it breaks: four honest failure modes

I don't want to sell you the dream without the gotchas. Here's what I've actually hit in the last two weeks.

Failure one: file-locality assumptions that aren't true. My first parallel run, I told four agents to "each take a module" and two of them ended up editing a shared config file because both modules imported from it. The auto-merge caught it, but I wasted the parallelism. The fix: in the prompt, list files each agent is allowed to touch. If you don't know the boundaries ahead of time, run one exploratory agent first to map the dependency graph, then fan out.

Failure two: agents making different assumptions. Agent 1 decided a helper should take a config object. Agent 3 decided the same helper should take positional args. Both made their own module work. Neither knew about the other. On merge, the types didn't line up. The fix: put shared interface decisions in CLAUDE.md before you fan out, or use an "architect agent" pass first that writes down the contracts, then spawn the workers. This is the pattern the Anthropic engineering team documented for their internal use.

Failure three: flaky tests that only fail in one worktree. This one spooked me. Agent 2's tests passed. I merged. Tests failed on main. Turned out one test depended on a global module cache that got populated by another test running earlier in the serial suite, and the worktree happened to run them in an order that masked the issue. The fix: always run the full suite on the merged result, not just the per-agent suites. Treat per-agent green as a necessary but not sufficient condition.

Failure four: the hardware bill. Four agents means four concurrent inference sessions. If you're on the metered tier, you'll feel it. Four agents running for 8 minutes is not four times the cost of one agent running for 32 minutes, but it's not cheaper either. On my Pro plan it's fine. On pay-per-token, watch your spend. I blew through $18 in an afternoon once by running three parallel jobs on a giant repo. I have a few other cost-control tricks in our list of 50 Claude Code tips.

There is also a case where you should just not use parallel agents: any task where the steps actually depend on each other. A migration where step 2 needs step 1's output is not parallel, it's a relay race. Pretending otherwise wastes time and gives you four broken branches. I have made this mistake. I will probably make it again. The test I use now, before I type /parallel, is a simple one: if I imagine each agent reporting back with only a file path list and a commit hash, can I stitch the results together without needing their intermediate reasoning? If yes, fan out. If no, stay serial.

Try it and tell me what breaks

Here is the thing I keep coming back to. The ceiling on what you can ship in a day is higher than you think, and it moved again this month. For a long time I treated Claude Code like a very fast pair programmer. One brain, one keyboard, take turns. Worktrees let me treat it like a small team.

I am still bad at this. I'm still learning what kinds of tasks fan out cleanly and which ones are secretly coupled. I still screw up the prompt and get four agents editing the same file. I still forget to clean up worktrees and then go "why do I have eleven folders with -agent- in the name." The tool is ahead of my instincts for how to use it, which is the sign of a tool worth practicing with.

If you try this, I want to know two things. What fan-out pattern worked for you? And where did the crews step on each other's feet? Send me your war stories. I'm collecting them, and I'll write up what I learn. The construction is getting faster. Let's figure out what else we can build now that we've got four hands instead of two.