How to run parallel Claude Code agents
Several agents on one repo is the fastest way to work, and the fastest way to get tangled changes. Worktrees keep them apart.
Published
The problem with one checkout
If two agents edit the same working directory, they overwrite each other’s files, trip over each other’s half-finished changes and fight over the same dev server port. The fix is to give each agent its own directory.
1. Create a worktree per task
From your repository:
git worktree add ../myapp-fix-auth -b fix-auth
git worktree add ../myapp-new-tests -b new-tests
Each directory is a full checkout on its own branch, sharing the same Git history. List them with git worktree list.
2. Start one agent in each
With tmux, one window per agent:
tmux new -s agents -n fix-auth -c ../myapp-fix-auth
claude
# Ctrl-b c opens a new window
cd ../myapp-new-tests && claude
Switch between windows with Ctrl-b and the window number.
3. Review and merge
When an agent is done, review its branch like any pull request, merge it, and remove the worktree:
git worktree remove ../myapp-fix-auth
4. Put it on a machine that stays on
Parallel agents are most useful on long tasks, which is exactly when your laptop sleeps or runs hot. Run them on a server that stays on (see keeping Claude Code running).
Or let Cube do the bookkeeping
Cube does all of the above for you on an always-on Linux computer in the cloud: every task gets its own worktree, every session is in the sidebar, and you can group a project’s agents and terminals on one screen. It works the same with Claude Code, Codex and other agents.
Questions
Can two Claude Code sessions work on the same repository?
Yes, as long as they don’t share a working directory. Give each its own Git worktree so each has its own branch and files.
What is a Git worktree?
A second (or third, or tenth) checkout of the same repository in another directory, each on its own branch, sharing one Git history. Changes in one don’t touch the others until you merge.
How many agents can I run at once?
It depends on the machine more than the agents. Each agent’s builds, tests and dev servers use CPU and memory, so a separate machine lets you run more than a laptop can.