How to run multiple Claude Code agents in parallel with git worktrees
Run several Claude Code sessions on one repo without conflicts. Set up git worktrees by hand or with claude --worktree, then clean up. A Paperclip AI guide.
To run several Claude Code agents on one repository, give each agent its own git worktree. A worktree is a separate checkout of your repository on its own branch. All worktrees share one .git history, so two agents never edit the same files.
This guide shows how to set up worktrees by hand, how to use Claude Code’s built-in --worktree option and how to clean up after you merge.
What you need
- Git 2.5 or newer
- Claude Code, installed and logged in
- A repository with at least one commit
Option 1: create worktrees by hand
1. Add a worktree for each task
Run these commands from your main checkout. Each command creates a folder and a branch.
git worktree add ../myapp-auth -b feature/auth
git worktree add ../myapp-billing -b fix/billing-rounding
Git checks out each new branch into its own folder next to your repository.
2. Install dependencies in each worktree
A new worktree has only the files that git tracks. It doesn’t have node_modules, build output or .env files.
cd ../myapp-auth
npm install
cp ../myapp/.env .env
3. Start Claude Code in each worktree
Open one terminal for each worktree and start a session:
cd ../myapp-auth && claude
cd ../myapp-billing && claude
Each session sees only its own folder, so the edits don’t collide.
4. Review and merge
Each agent commits to its own branch. Push the branch and open a pull request in the usual way:
git push -u origin feature/auth
Option 2: use claude --worktree
Claude Code can create the worktree for you. Give each session a name:
claude --worktree feature-auth
Run the same command with another name in a second terminal to start a second isolated session. To copy gitignored files such as .env into each new worktree, list them in a .worktreeinclude file. The Claude Code worktree docs cover cleanup and other options.
Clean up
List your worktrees:
git worktree list
After you merge a branch, remove its worktree and delete the branch:
git worktree remove ../myapp-auth
git branch -d feature/auth
If you deleted a worktree folder by hand, remove the stale entry:
git worktree prune
Common problems
”fatal: ‘feature/auth’ is already checked out”
Git lets you check out a branch in only one worktree at a time. Create a new branch for the second worktree, or remove the first one.
Two dev servers use the same port
Each worktree runs its own dev server. Give each one its own port, for example PORT=3001 npm run dev.
The agent can’t find environment variables
The new worktree doesn’t have your .env file. Copy the file, or list it in .worktreeinclude when you use claude --worktree.
Disk space grows fast
Each worktree has its own dependencies and build output. Remove a worktree after you merge its branch.
When this setup stops scaling
Worktrees fix file conflicts. At five or more agents, other problems appear:
- You lose track of which terminal works on which task.
- A reboot closes every session.
- Nobody checks a branch before it reaches review.
- One agent in a loop can use your whole token budget.
- Old worktrees and branches pile up.
Paperclip handles these parts. Turn on Isolated Workspaces, and Paperclip can give each task its own worktree and branch, with setup and teardown commands for each project. You assign the task to Claude Code, Codex or another coding agent, and the agent uses the login that you already have. Each task keeps its thread, its diff and its run history. A budget pauses an agent at its limit, and a Review stage keeps the task open until you approve it.
npx paperclipai@latest onboard --yes
FAQ
Is a git worktree the same as a clone?
No. A clone copies the whole repository, including its history. A worktree is an extra checkout that shares the history of the original repository. Worktrees use less disk space, and a commit in one worktree is visible in all of them.
Can two worktrees use the same branch?
Not by default. Git refuses to check out a branch that another worktree already uses.
How many Claude Code sessions can I run at once?
Git sets no limit. Your machine, your plan’s rate limits and the time that you have to review the output set the real limit.
Does Codex work the same way?
Yes. Any coding agent that works in a folder can work in a worktree. Start the agent from inside the worktree folder.
Sources
- Git, git-worktree documentation, checked November 10, 2026
- Anthropic, Claude Code common workflows: run parallel sessions with worktrees, checked November 10, 2026