> ai agents & parallel sessions
The reason worktrees went from niche to essential: AI coding agents. Claude Code, Codex, Cursor, and orchestrators like Orca all run agents that edit files, run builds, and commit — and a single checkout can only serve one of them at a time. One worktree per agent gives each its own directory, branch, and index while sharing the repository, so a fleet of agents works simultaneously and their results land as sibling branches you can diff, test, and merge. This section is the full lifecycle: fan out, provision, monitor, compare, integrate, tear down.
// ai agents & parallel sessions
9 commands$ git worktree add -b agent/auth ../myapp-agent-auth main$ claude --worktree feature-auth$ for t in auth search billing; do git worktree add -b agent/$t ../myapp-agents/$t main; done$ cp .env .env.local ../myapp-agent-auth/ 2>/dev/null$ pnpm install --dir ../myapp-agent-auth$ tmux new-session -d -s agents -n auth -c ../myapp-agents/auth$ git diff main...agent/auth$ git merge agent/auth$ git worktree remove --force ../myapp-agents/auth// faq
Why do AI agents need worktrees instead of sharing one checkout?
An agent doesn't just read code — it edits files, stages, commits, and runs dev servers and tests. Two agents in one directory overwrite each other's edits, stage each other's half-done work into commits, fight over .git/index.lock, and trigger each other's file watchers. A worktree per agent removes every one of those collisions while keeping all the results in one repository.
Should each agent get a worktree or a full clone?
Worktrees, almost always. They're created in milliseconds without duplicating history, every agent's branch is visible to you and to the other worktrees instantly (so you can diff and merge without any push/pull), and one git fetch serves everyone. Reach for separate clones only when you need hard isolation — say, an agent that must not see other branches or needs a different set of remotes.
How do Claude Code, Codex, and Orca actually use worktrees?
Claude Code has it built in: claude --worktree <name> starts a session inside a managed worktree, and its subagents can run in ephemeral worktrees that are cleaned up automatically when left unchanged. Orchestrators like Orca create a worktree per task and hand each one to an agent. For tools without built-in support, the manual recipe works everywhere: create a worktree and branch, launch the agent with its working directory inside it, review the branch when it finishes.
What's missing from a fresh worktree that agents trip over?
Everything untracked: .env files, node_modules, build caches, local databases, tool state. The agent then fails at runtime rather than at checkout, which is confusing to debug. Provision each worktree right after creating it — copy env files, install dependencies (cheap with pnpm's shared store), and give each dev server its own port.
How do I get five agents' work back into main?
Each agent commits to its own branch, so integration is ordinary Git from your main checkout: three-dot diff each branch to review it, merge the winner, cherry-pick the good pieces from the others, or push the branches and open PRs for CI and human review. Then remove the worktrees and delete the branches so the repository doesn't accumulate ghosts.