Stu Mason

One Claude Code session is productive. Three running in parallel is a different thing entirely. I went from finishing one feature per session to shipping three branches in the time it used to take me to ship one. The trick is not magic — it is git worktrees, careful task splitting, and letting each agent work independently without stepping on the others.

This guide covers how I actually do it. Real commands, real file paths, real mistakes I made along the way.

The Prerequisite: Git Worktrees

Before you can run parallel Claude Code sessions on the same repo, you need to solve a fundamental problem: each session needs its own working directory. If two Claude Code instances are editing files in the same directory, you get race conditions, corrupted state, and a bad time.

Git worktrees solve this perfectly. A worktree is a linked copy of your repository that shares the same .git history but has its own working directory and its own checked-out branch. No duplication of the repo, no separate clones to keep in sync.

Setting Up Worktrees

From your main project directory, create worktrees for each parallel task:

# From your project root
cd ~/Code/progress

# Create worktrees for parallel work
git worktree add ../progress-api -b feature/new-api-endpoint
git worktree add ../progress-frontend -b feature/dashboard-page
git worktree add ../progress-tests -b feature/test-coverage

Each command creates a new directory alongside your project with its own branch checked out. Your filesystem now looks like this:

~/Code/
├── progress/              # main branch (your primary repo)
├── progress-api/          # feature/new-api-endpoint
├── progress-frontend/     # feature/dashboard-page
└── progress-tests/        # feature/test-coverage

Each directory is a fully functional working copy. You can cd into any of them and run claude independently.

Managing Worktrees

A few commands you will use regularly:

# List all worktrees
git worktree list

# Remove a worktree after merging its branch
git worktree remove ../progress-api

# Prune stale worktree references
git worktree prune

One important constraint: each branch can only be checked out in one worktree at a time. This is actually a feature — it prevents two sessions from accidentally working on the same branch.

How I Split Work Across Agents

The single most important rule: no two agents should touch the same files. If agent one is editing UserController.php and agent two is also editing UserController.php, you are setting yourself up for merge conflicts that negate any time you saved.

Good Splits

The splits that work well follow natural boundaries in your codebase:

Backend + Frontend + Tests — This is my default split. One agent builds the API endpoint (controller, action, migration, form request). Another builds the React page that will consume that API. A third writes tests for existing or new features. These three workstreams rarely touch the same files.

Independent features — If you have three features on the backlog that touch different parts of the app, run them in parallel. Feature A adds a notification system (new model, new migration, new controller). Feature B redesigns the settings page (frontend-only changes). Feature C adds CSV export to an existing page (new action class, updated controller method).

Refactor + Feature + Tests — One agent refactors a service class. Another builds a new feature in a different part of the app. The third adds test coverage to a third area. Clean separation.

Bad Splits

Both agents editing routes/web.php — Route files are a shared resource. Two agents adding routes to the same file means merge conflicts every time.

Concurrent migrations — If two agents create migrations with timestamps seconds apart, you get ordering issues. Worse, if both modify the same table, the second migration may fail because it expects a different schema than what exists.

Same component, different features — Two agents both adding props to the same React component or both modifying the same Blade template. These changes look small but produce messy conflicts.

A Real Example From My Project

Here is an actual parallel session I ran on this project — a Laravel + Inertia + React application.

The Setup

I had three tasks to complete:

Build an API endpoint for fetching article statistics
Build a dashboard page showing those statistics
Write tests for the existing article CRUD functionality

Task Split

Agent 1 — Backend API (worktree: progress-api, branch: feature/article-stats-api)

app/Actions/Article/GetArticleStats.php — new action class
app/Http/Controllers/Api/ArticleStatsController.php — new controller
app/Http/Requests/ArticleStatsRequest.php — form request validation
database/migrations/xxxx_add_view_count_to_articles.php — schema change
routes/api.php — one new route

Agent 2 — Frontend Dashboard (worktree: progress-frontend, branch: feature/stats-dashboard)

resources/js/Pages/Dashboard/Stats.tsx — new page component
resources/js/Components/Charts/ArticleChart.tsx — new chart component
resources/js/Components/Stats/StatCard.tsx — new reusable card
resources/css/app.css — minor style additions

Agent 3 — Test Coverage (worktree: progress-tests, branch: feature/article-crud-tests)

tests/Feature/Article/CreateArticleTest.php — new test file
tests/Feature/Article/UpdateArticleTest.php — new test file
tests/Feature/Article/DeleteArticleTest.php — new test file

Notice the zero file overlap. Agent 1 owns the backend. Agent 2 owns the frontend. Agent 3 owns the test directory. The only potential collision point is if agent 2 needs to reference a controller that agent 1 is still building — which is why the frontend agent worked from an agreed API contract rather than importing directly from the backend.

Starting the Sessions

I use tmux to manage the terminal sessions, but multiple tabs work just as well:

# Terminal 1 — Backend API
cd ~/Code/progress-api
claude

# Terminal 2 — Frontend Dashboard
cd ~/Code/progress-frontend
claude

# Terminal 3 — Test Coverage
cd ~/Code/progress-tests
claude

Each session picks up the project's CLAUDE.md automatically, so every agent knows the coding standards, project structure, and conventions. I give each agent a focused prompt describing only its task.

Tmux Layout

If you use tmux, here is a quick layout for monitoring three sessions:

# Create a new tmux session
tmux new-session -s parallel -c ~/Code/progress-api

# Split into three panes
tmux split-window -h -c ~/Code/progress-frontend
tmux split-window -v -c ~/Code/progress-tests

# Start Claude in each pane
tmux send-keys -t 0 'claude' Enter
tmux send-keys -t 1 'claude' Enter
tmux send-keys -t 2 'claude' Enter

Managing the Workflow

CLAUDE.md Does the Heavy Lifting

Each worktree gets the same CLAUDE.md because it is checked into the repo. This is the single biggest enabler of parallel sessions. Every agent knows:

The project structure and conventions
How to run tests
Which generators to use
The git workflow (feature branches, PRs, never commit to main)

If you have session-specific instructions, you can create a .claude/ directory in the worktree root with additional context. I rarely need this — the shared CLAUDE.md covers most cases.

Monitoring Progress

I check in on each session periodically. Claude Code shows its current activity in the terminal, so a quick glance at each tmux pane tells me where things stand. If one agent finishes early, I can give it a new task while the others continue.

One thing I have learned: resist the urge to micromanage. Give each agent a clear task, let it work, and review the output when it is done. Constantly interrupting with follow-up instructions slows things down more than it helps.

Merging and Conflict Resolution

The PR Workflow

Each agent creates a PR from its feature branch:

# From each worktree, after the agent finishes
gh pr create --title "feat: article stats API" --body "Adds endpoint for article statistics"

I review each PR independently. This is important — reviewing three small, focused PRs is significantly faster than reviewing one massive PR with mixed concerns.

Merge Order Matters

If agent 2's frontend work depends on agent 1's API, merge the API branch first:

Merge feature/article-stats-api into main
Rebase feature/stats-dashboard onto the updated main
Merge feature/stats-dashboard
Merge feature/article-crud-tests (independent, can go in any order)

# After merging the API branch
cd ~/Code/progress-frontend
git fetch origin
git rebase origin/main
# Resolve any conflicts, then push
git push --force-with-lease

When Conflicts Happen

Even with careful splitting, minor conflicts happen. The most common culprit is shared config files — routes/web.php, app.css, or auto-generated files like TypeScript type definitions.

When it happens, resolve manually. It is usually a matter of keeping both additions. Two agents adding different routes to the same file just need both routes in the final version.

Gotchas and Lessons Learned

Migrations need a single owner. If two agents create migrations simultaneously, you get timestamp conflicts and potential schema issues. Assign migration creation to one agent, or stagger them so the first agent's migrations are committed before the second agent starts.

Shared files need an owner. Route files, config files, and the main CSS file should be assigned to one agent. Other agents can note what they need added, and the owner agent handles it.

Each session is isolated. There is no shared memory between Claude Code sessions. Agent 1 cannot tell agent 3 what it discovered about a bug. If you need to transfer context, you do it manually — copy the relevant output and paste it into the other session.

Cost is linear. Three parallel sessions means three times the API usage. Each session runs its own conversation with the full context window. This adds up. Make sure the time savings justify the cost, which for me they always do on substantial tasks.

Worktrees share the git object store. This is a feature, not a bug — but it means git gc and other maintenance operations affect all worktrees. Run them from the main repo when no sessions are active.

Install dependencies in each worktree. Each worktree needs its own vendor/ and node_modules/. Run composer install and npm install in each worktree before starting Claude Code:

cd ~/Code/progress-api && composer install && npm install
cd ~/Code/progress-frontend && composer install && npm install
cd ~/Code/progress-tests && composer install && npm install

When to Go Parallel vs. Sequential

Go Parallel When:

Features are independent with no shared files
You are splitting frontend, backend, and tests
You have multiple small tasks that each take 15-30 minutes
You are writing test coverage for different parts of the app
You are building out multiple pages that do not share components

Stay Sequential When:

Changes depend on each other (schema first, then code using it)
You are refactoring shared utilities or base classes
The work involves a single complex feature touching many files
You are debugging an issue that requires deep investigation
Database schema changes need careful ordering

The Productivity Multiplier

The first time I ran three agents in parallel and merged all three PRs within an hour, it changed how I think about development velocity. It is not about working faster — each individual agent works at the same speed. It is about eliminating idle time. While agent 1 is writing tests, agent 2 is building UI, and agent 3 is setting up an API. No one is waiting on anyone.

The key is preparation. Spend five minutes planning the split before you start. Identify the file boundaries. Set up your worktrees. Write clear prompts for each agent. That five minutes of planning saves an hour of merge conflict resolution.

Git worktrees are the enabling technology here. Without them, you are stuck with separate clones, duplicated repos, and sync headaches. With them, parallel Claude Code sessions become a natural extension of a feature-branch workflow. You are already branching for every feature — now you are just working on three branches at once.

Running Parallel Claude Code Agents on Real Projects