I had a deadline, so I ran three Claude Code agents in parallel. Three features needed to ship by Friday: a new share modal, a folder management system, and a template customizer. Each one was a full day of work. It was Wednesday morning.

Instead of building them sequentially, I ran three Claude Code instances in parallel, each in its own git worktree, each working on a separate feature branch. By Thursday afternoon, all three features were merged, tested, and deployed.

This is not a magic trick. It works because of a specific property of git worktrees: they give you completely isolated working directories from the same repository, each checked out to a different branch. No conflicts during development. No stepping on each other's files. Three agents, three branches, one repo.

Here's how I set it up, when it actually makes sense, and when you should avoid it entirely.

What git worktrees are (and why they matter for parallel agents)

Most developers work with a single checkout of their repository. One directory, one branch at a time. If you want to switch branches, you stash or commit your work, check out the new branch, and context-switch.

Git worktrees let you have multiple working directories from the same repo, each on a different branch, all at the same time. They share the same .git history but have completely independent file states.

# Create three worktrees from your main repo
git worktree add ../myproject-share-modal feature/share-modal
git worktree add ../myproject-folders feature/folders
git worktree add ../myproject-customizer feature/customizer

After running these commands, you have four directories: your original repo (on main) and three worktree directories, each on its own feature branch. They're real directories with real files. You can open each one in a separate terminal and run a separate Claude Code instance in each.

This is the key insight: because each worktree is a fully independent checkout, there's zero interference between agents. Agent A can rewrite the share modal component while Agent B creates new folder management files while Agent C refactors the template system. They never touch the same working directory.

Approach 1: Manual worktrees (DIY)

This is what I used for the three-feature sprint. It's more work to set up, but you have complete control over every step.

Step 1: Create the worktrees

From your main repo directory:

# Make sure main is up to date
git pull origin main

# Create feature branches and worktrees
git worktree add ../app-share-modal feature/share-modal
git worktree add ../app-folders feature/folders
git worktree add ../app-customizer feature/customizer

Each worktree starts from main, so all three agents begin with the same codebase.

Step 2: Install dependencies in each worktree

Each worktree is a separate directory. If your project has node_modules, each worktree needs its own copy.

cd ../app-share-modal && npm install
cd ../app-folders && npm install
cd ../app-customizer && npm install

Yes, this means three copies of node_modules. For a typical Next.js project, that's 500MB to 1GB per worktree. Plan your disk space accordingly.

Step 3: Launch Claude Code in each worktree

Open three terminal tabs (or use tmux/screen) and launch Claude Code in each:

# Terminal 1
cd ../app-share-modal
claude

# Terminal 2
cd ../app-folders
claude

# Terminal 3
cd ../app-customizer
claude

Each instance gets its own CLAUDE.md context from the worktree. If your project uses a hub-and-spoke memory system, each agent reads the same memory files (they're in the shared git history) but writes to its own branch.

Step 4: Give each agent a clear, scoped task

This is where the quality of your context engineering matters. Each agent needs to know exactly what it's building and, critically, what it should not touch.

In Terminal 1:

Build a new share modal component. Only modify files in src/components/app/share-modal/
and src/app/api/share/. Do not modify any other components. Write tests in tests/components/.

In Terminal 2:

Build a folder management system. Create new files in src/components/app/folders/ and
src/lib/supabase/folders.ts. Add API routes in src/app/api/folders/. Do not modify
existing components. Write tests.

In Terminal 3:

Build a template customizer panel. Work in src/components/app/customizer/ and
src/lib/templates/customizer.ts. Do not modify the existing template registry.
Write tests.

The explicit "do not modify" boundaries are essential. Without them, two agents might both decide to update a shared layout component or a common utility function, creating merge conflicts later.

Step 5: Monitor and merge

While the agents work, I check in on each terminal periodically. When an agent finishes, I review its branch, run the tests, and merge:

# Back in the main repo
git checkout main
git merge feature/share-modal
git merge feature/folders
git merge feature/customizer

If I scoped the work correctly, these merges are clean. If two agents touched the same file, I resolve the conflict manually. More on that in the gotchas section.

Step 6: Clean up worktrees

git worktree remove ../app-share-modal
git worktree remove ../app-folders
git worktree remove ../app-customizer
git branch -d feature/share-modal feature/folders feature/customizer

Approach 2: Subagents with worktree isolation (built-in)

Claude Code's Agent tool supports an isolation: "worktree" parameter that handles worktree creation and cleanup automatically. Instead of managing everything yourself, you let the parent agent spawn child agents, each in its own worktree.

This is cleaner for orchestrated workflows where a single Claude Code session needs to parallelize work.

Here's how it works in practice. You start a single Claude Code session and describe the overall goal:

I need three features built in parallel:
1. Share modal redesign
2. Folder management
3. Template customizer

Use subagents with worktree isolation for each feature.

Claude Code spawns three subagents, each in an automatically created worktree. Each subagent works on its assigned feature, commits the result, and the parent agent merges the branches back.

The advantages over the manual approach:

Automatic worktree creation and cleanup. No manual git worktree add/remove commands.
The parent agent coordinates. It can review each subagent's output before merging.
Shared context. The parent agent can pass specific instructions to each subagent.

The tradeoffs:

Less visibility. You don't see each agent's work in real time the way you do with separate terminals.
Token cost is higher. The parent agent consumes tokens for orchestration on top of the subagents' token usage.
Less control over recovery. If a subagent hits a problem, the parent agent decides how to handle it. In the manual approach, you intervene directly.

I use this approach for smaller parallelization tasks: "refactor these three modules" or "write tests for these five files." For larger features where I want to monitor progress and provide guidance, I prefer the manual approach.

Approach 3: Agent Teams (experimental)

Claude Code v2.1.32 introduced Agent Teams as a research preview. This takes parallel agents further by adding built-in coordination: agents claim tasks from a shared queue, merge changes continuously, and resolve conflicts automatically.

Instead of defining explicit boundaries for each agent, you describe the overall work and let the team figure out the division:

Ship these three features by end of day: share modal, folder management,
template customizer. Coordinate as a team.

The agents self-organize. One might claim the share modal, another the folders. They merge incrementally rather than waiting until the end. If two agents need to modify the same file, the coordination layer handles the conflict resolution.

This sounds ideal, and sometimes it is. But it's experimental for good reason.

In my testing, Agent Teams works well for tasks that are clearly separable. Refactoring five independent modules, writing tests for different parts of the codebase, or generating documentation for separate features. The automatic coordination handles these cases gracefully.

Where it gets unpredictable is with tasks that have subtle dependencies. Two agents might both decide they need to update a shared type definition. The automatic conflict resolution picks one version, which might break the other agent's work. In the manual approach, I'd catch this during the merge step. With Agent Teams, it can cascade into a chain of fixes.

My recommendation: use Agent Teams for clearly parallelizable work where the individual tasks are well-defined and independent. For anything with shared state or cross-cutting concerns, stick with manual worktrees or scoped subagents where you control the boundaries.

When parallel agents make sense

After running parallel agents across a dozen sessions, I've found four scenarios where the setup overhead is genuinely worth it.

Independent features with no shared code changes. This is the sweet spot. Three features that live in different directories, touch different files, and share no common modifications. The three-feature sprint I described at the top was exactly this pattern.

Deadline pressure where sequential work is too slow. If each feature takes 4-6 hours of agent time and you need all three by tomorrow, parallel is the only option. The setup overhead is 15-20 minutes. The time savings can be an entire day.

Exploratory work with multiple approaches. Sometimes I don't know the right solution. I'll spin up three agents, each trying a different architectural approach to the same problem. After they finish, I review all three, pick the best one, and discard the other two. This is expensive in tokens but cheap in human decision-making time.

Large refactors that split cleanly by module. "Migrate all API routes to the new validation middleware" is a task that splits naturally. Each route file is independent. Five agents can each take a batch of routes, and the merges will be clean because each agent modifies different files.

When parallel agents do NOT make sense

Here's the honest part: 95% of my Claude Code sessions are sequential. Parallel agents are a tool for specific situations, not a default workflow.

Interdependent features that touch the same files. If Feature A modifies the database schema and Feature B reads from that schema, they can't run in parallel. One agent's changes will break the other's assumptions. You'll spend more time resolving conflicts than you saved.

Small tasks where setup overhead exceeds time savings. Creating three worktrees, installing dependencies, and launching three Claude Code instances takes 15-20 minutes. If the total work is an hour, you've spent a quarter of your time on infrastructure.

When you can't clearly define the scope for each agent. Parallel agents need explicit boundaries. "Build this vague feature" doesn't parallelize. If you can't write a crisp one-paragraph brief for each agent, the work isn't ready for parallelization.

When token budget matters. Three agents working for an hour each consume three hours of tokens. If you're on a metered plan, parallel agents multiply your costs linearly. There's no efficiency gain on the token side; you're paying for speed with money.

Gotchas and lessons learned

Token costs multiply. Three parallel agents use roughly 3x the tokens of one sequential agent doing the same work. Sometimes more, because each agent independently reads shared files (package.json, tsconfig, shared utilities) that a sequential agent would only read once. Factor this into your cost calculations.

Merge conflicts from unexpected shared files. Even with careful scoping, agents sometimes modify files you didn't expect. Both agents might update the same barrel export file. Both might add imports to a shared constants file. Both might modify the test configuration. My rule: list the shared files explicitly in each agent's instructions and tell it not to modify them.

Each worktree has its own node_modules. For a Next.js project with typical dependencies, that's 500MB to 1GB per worktree. Three worktrees can eat 2-3GB of disk space. Clean them up promptly when the work is done.

CLAUDE.md applies to all worktrees. If your CLAUDE.md references absolute paths, those paths might not exist in the worktree directory. Use relative paths in your CLAUDE.md, or be aware that worktree agents might not find project-specific configuration files.

Agent Teams coordination is unpredictable. I've seen Agent Teams produce elegant task division and clean merges. I've also seen it enter loops where two agents repeatedly modify the same file, each "fixing" the other's changes. The research preview label is accurate. Use it for low-stakes parallelization, not production-critical deadline work.

Dev server conflicts. If your agents need to run a dev server (for testing, hot reload), each worktree needs a different port. Pass PORT=3001, PORT=3002, etc. to each agent's environment, or they'll fight over the default port.

Consolidating the output

After merging three feature branches, I have a pile of individual outputs: each agent's commit messages, test results, and sometimes documentation. The code merges through git, but the narrative around the changes needs consolidation.

Each agent generates its own output: docs, changelogs, test reports. When the work merges, I consolidate the documentation into a single changelog and publish it through Unmarkdown™ so the team can review formatted output, not raw markdown diffs.

For the three-feature sprint, I wrote a single changelog entry covering all three features, ran it through a template that matched our docs style, and published it. Three branches of work, one coherent update. The alternative (sending three separate markdown files or, worse, telling people to read the git log) doesn't scale to teams.

The workflow, summarized

For anyone who wants to try this, here's the minimal version:

Identify 2-4 independent tasks with clear file boundaries.
Create a worktree for each: git worktree add ../project-feature feature/name.
Install dependencies in each worktree.
Launch Claude Code in each with explicit scope instructions.
Monitor progress. Intervene if an agent goes off track.
Merge branches back to main. Resolve conflicts if needed.
Run the full test suite on main after all merges.
Clean up worktrees: git worktree remove ../project-feature.

For simpler cases, use subagents with isolation: "worktree" and let Claude Code handle the orchestration. For clearly separable batch work, try Agent Teams.

The real lesson

Parallel agents are not about doing more work. They're about compressing calendar time when you have tasks that are genuinely independent. The total token cost is the same or higher. The total human oversight is higher (you're monitoring three agents instead of one). The only thing that shrinks is wall-clock time.

That's valuable in specific situations. Deadlines, exploration, large refactors. But the overhead of scoping, launching, monitoring, and merging means it only pays off when the individual tasks are substantial enough (at least 1-2 hours of agent work each) and independent enough (different files, different directories, no shared mutations) to justify the setup.

Most of the time, one agent working sequentially through a well-structured context is faster, cheaper, and produces cleaner results. I've built an entire SaaS product across 200+ sequential sessions. Parallel agents were useful for maybe ten of those sessions.

But for those ten sessions, they saved me days. That's worth knowing how to do.

Running Parallel Claude Code Agents with Git Worktrees