Step by step · built from 5 real setups
How to run Claude Code agents in parallel with git worktrees
Last updated · by Thomas, editor · How we verify
One worktree per agent, one task per worktree, and you only look at the session that needs you. These steps come from the Claude Code team's own habits and four other published setups.
What you need
- Claude Code or Codex CLI
- A git repo; each agent gets its own worktree
- Optional: Agent Navigator (open source, macOS) or tmux to switch between sessions
- Tests or CI each agent can run
Set it up, step by step
- Split the work into tasks that touch different files. Parallel tasks editing the same file still conflict. (recipe)
- Create one worktree per task:
git worktree add ../wt-[BRANCH] -b [BRANCH]. The Claude Code team runs 3 to 5 sessions; start with 3. (recipe) - Write a done-when list for each task: checks a program can run, like tests or CI going green. (recipe)
- Start each session in plan mode, and have a second session review the plan before it builds. (recipe)
- Give each agent the bounded prompt below: stay in its worktree, write NEEDS INPUT when blocked, DONE plus a summary and test command when finished. (recipe)
- Add a Notification hook so a desktop alert names the folder that's waiting. (recipe)
- Review one branch at a time: run the checks yourself, merge, then
git worktree remove. Commit first; plain git doesn't warn about uncommitted work. (recipe)
Starter prompt: one bounded task per worktree (our version, from the kanban recipe)
Notification hook prompt (from the notify recipe)
Approval and safety rules
- Keep permission prompts on. Don't run parallel agents with permissions skipped. (recipe)
- A report is not proof: run the real checks. Stop a loop after two failed tries and rethink the plan. (recipe)
- Routine, easy-to-revert changes merge after CI; critical ones (data, auth, billing, migrations) wait for an independent review and a human merge. (recipe)
- Read any hook before installing it: hooks run shell commands. (recipe)
- Watch shared resources. Shared dev databases and several Docker stacks at once break parallel runs. (recipe)
Real examples
Each one links to the recipe and its original source.
- The Claude Code team's habits: parallel worktrees, plan first, skillsThe Claude Code team: 3–5 sessions in parallel worktrees, plan mode first.
- Run several coding agents on a kanban boardAn open-source board that sorts agents into Idle, Working and Needs Input.
- Get notified when your coding agent needs youA hook that pings you whenever Claude Code is waiting on you.
- Split a big task into a DAG of small subagentsA plugin that splits big tasks into a graph of small subagents in parallel worktrees.
- Done-when lists and a two-try stop ruleA lead agent hands bounded pieces to other models, each in its own worktree.
Compare more setups: Parallel coding agents: all 9 recipes →
Common questions
Why use git worktrees for parallel agents?
Each worktree is its own checkout on its own branch, so agents don't edit the same working files. Every setup here gives each agent its own worktree.
How many Claude Code agents can I run at once?
The Claude Code team runs 3 to 5 sessions. The limit people hit is review: too many sessions overloads your review capacity.
Does this work with Codex?
Yes. Agent Navigator supports Claude Code and Codex CLI, and the done-when rules work from either one.
Get the next money recipe. Free.
New recipes every week, plus the top 10 agent setups pack. One email, no spam.
Unsubscribe anytime. Privacy
More guides: Make money with AI agents · AI voice agent business · AI agent agency ideas · Claude Code use cases · Grok Bot use cases · Claude Code vs Codex · AI agents for small business · AI email agents · AI code review agents · Parallel coding agents · AI agents that save you money · Autonomous agents that made money