How to run multiple Claude Code sessions in parallel with git worktrees

Claude Code spends most of its wall-clock time working without you. It reads files, runs tests, edits code, runs tests again. During that stretch you’re doing exactly one thing: waiting.

Serialize your tasks and that wait compounds. Agent works, you idle. You review, agent idles. A three-task afternoon becomes a whole day of taking turns.

The fix is to run multiple sessions at once, each on its own task. The problem is that two agents editing the same checkout will trample each other. One runs git checkout, the other’s diff evaporates. The answer to that is git worktrees, and it’s the approach Anthropic’s own docs recommend for parallel sessions.

Git worktrees in 60 seconds

A worktree is a second (or third, or fifth) working directory attached to the same repository. Each worktree has its own files and its own checked-out branch, but they all share one object store and one history. No re-cloning, no duplicated .git data, and a commit made in one worktree is instantly visible to the others.

The commands you actually need:

# New worktree on a new branch
git worktree add ../myapp-feature-auth -b feature-auth

# New worktree from an existing branch
git worktree add ../myapp-bugfix bugfix-123

# See what you've got
git worktree list

# Tear one down
git worktree remove ../myapp-feature-auth

One rule keeps this sane: one worktree per task, one branch per worktree. Git enforces half of it for you — the same branch can’t be checked out in two worktrees at once.

The setup

Say you have three tasks: an auth feature, a flaky-test fix, and a docs pass. Create a worktree for each, then open a terminal tab per worktree and start Claude in it:

git worktree add ../myapp-feature-auth -b feature-auth
git worktree add ../myapp-fix-flaky-tests -b fix-flaky-tests
git worktree add ../myapp-docs-cleanup -b docs-cleanup

# Tab 1
cd ../myapp-feature-auth && claude

# Tab 2
cd ../myapp-fix-flaky-tests && claude

# Tab 3
cd ../myapp-docs-cleanup && claude

Give each session its prompt and let them run. Each Claude only sees its own directory, so edits never collide. Name worktrees after the task, not the date or a number — when you have four tabs open, myapp-fix-flaky-tests tells you which tab you’re staring at and myapp-wt2 does not.

Or skip the ceremony: claude --worktree

Claude Code now does the worktree dance for you. Pass --worktree (or -w) and it creates the worktree, branches it, and starts the session inside:

# Terminal 1
claude --worktree feature-auth

# Terminal 2
claude --worktree bugfix-123

By default the worktree lands in .claude/worktrees/<name>/ at your repo root, on a branch named worktree-<name>. Omit the name and Claude invents one like bright-running-fox. New worktrees branch from origin/HEAD — a clean tree matching the remote — unless you set worktree.baseRef to "head" in settings to branch from your local state instead. You can even branch straight off a pull request with claude --worktree "#1234".

Two housekeeping notes from the official docs: add .claude/worktrees/ to your .gitignore, and run plain claude once in the repo first to accept the trust dialog before --worktree will work.

Reusing a name resumes that worktree. And cleanup is mostly automatic: exit a session with no commits and no changes, and the worktree and branch are removed for you. If there’s work in flight, Claude asks whether to keep or delete. Manual worktrees you clean up yourself with git worktree remove.

There’s also a middle path: subagents inside a single session can each get their own worktree (isolation: worktree in the agent’s frontmatter, or just ask Claude to “use worktrees for your agents”). That parallelizes within one conversation instead of across terminals.

The gotchas nobody mentions until you hit them

Each worktree is a fresh checkout. Gitignored files don’t come along. No node_modules, no .env, no virtualenv. You’ll run npm install (or equivalent) per worktree, and yes, that’s N copies of node_modules on disk. For env files, Claude Code reads a .worktreeinclude file at your project root — gitignore syntax, and it copies matching gitignored files into every new worktree:

.env
.env.local
config/secrets.json

Port collisions. Three dev servers all want :3000. Either tell each session up front — “run the dev server on port 3001” — or make the port an env var and vary it per worktree. Same story for local databases and docker-compose project names.

Merging. Each worktree is a branch, so this is just normal git. Small, frequent merges beat one heroic integration at the end. Land tasks one at a time, rebase the survivors. If two sessions both touched the same module, you signed up for that conflict when you assigned overlapping tasks — which brings us to:

When not to parallelize. Skip worktrees when tasks touch the same files (you’re just moving the collision from the filesystem to the merge), when a task depends on another’s output, or when the task needs your judgment at every step. One deep, carefully-reviewed session beats three shallow ones for anything architectural. Parallelism is for independent work: a feature here, a bugfix there, a refactor in the corner.

The real cost: you become the bottleneck

Here’s the part most “10x with parallel agents” posts skip. The constraint was never terminal count. It’s you.

Every session periodically stops and wants something: a permission to run a command, a clarifying question, a plan to approve, a finished diff to review. With one session that’s a conversation. With four, it’s a pager rotation. You alt-tab to terminal 2, rebuild context on what the auth task was doing, approve, and by then terminal 4 has been sitting idle for six minutes waiting on a yes/no you didn’t see.

That’s attention fragmentation, and it has a real ceiling. Most people top out around three or four concurrent sessions before the context-switching tax eats the throughput gains. You can raise the ceiling — looser permission settings for low-risk tasks, plan mode so you approve a whole plan up front instead of drip-approving commands, batching your check-ins instead of reacting to every prompt — but you can’t remove it. Parallel agents don’t eliminate your work; they compress it into interrupts.

Go in knowing that, size your fleet to your attention, and it’s still a huge win. Pretend it’s free and you’ll end up babysitting four terminals while getting less done than with one.

---

This is the exact problem we’re building Vyber for: a mission-control iPhone app for parallel Claude Code sessions, with an interrupt inbox for everything your agents are blocked on and a fleet board showing every session’s state at a glance — so you can unblock terminal 4 from the coffee line instead of the desk. There’s a waitlist at vybercode.net if that sounds like your afternoon.