DEV Community

AgentKoji
AgentKoji

Posted on Originally published at agentkoji.com

Run Parallel AI Agents with Git Worktrees

#claudecode #git #productivity #ai

Two agents in one working tree step on each other's edits. The fix is to give each Claude Code session its own directory and branch with git worktree. Here's the condensed version (tested on git 2.54.0 and Claude Code 2.1.309, 2026-10-23).

Git worktree basics 

cd todo-app
git worktree add ../todo-app-login -b feature/login
git worktree list
Enter fullscreen mode Exit fullscreen mode

Things that bite:

  • A branch can be checked out in only one worktree at a time. A second one fails with fatal: 'feature/login' is already used by worktree at ...
  • git worktree remove refuses while modified or untracked files remain
  • If you delete a worktree with rm, clean up with git worktree prune -v

Claude Code's --worktree 

claude --worktree feature-auth
Enter fullscreen mode Exit fullscreen mode

This creates .claude/worktrees/feature-auth/ on a new branch worktree-feature-auth. Run it in another terminal with a different name for a second session. Add .claude/worktrees/ to .gitignore. New worktrees branch from the default branch; set worktree.baseRef to "head" to branch from current work.

What each worktree needs

A worktree is a fresh checkout: no node_modules, no gitignored .env. Install dependencies in each one. A .worktreeinclude file (gitignore syntax) copies matching gitignored files into new worktrees:

.env
.env.local
Enter fullscreen mode Exit fullscreen mode

Dev-server ports and local databases are shared, so give each worktree its own port.

How many to run

On a subscription, usage is shared across sessions (five-hour and weekly limits), so more sessions hit limits sooner. The costs docs say agent teams use roughly 7x more tokens than standard sessions when teammates run in plan mode. We found no official maximum.

Cleaning up

  • Interactive session with no changes: an unnamed worktree and its branch are removed automatically
  • With changes: you're asked to keep or remove; resume with claude --worktree <name> --resume
  • -p runs leave worktrees behind; remove them with git worktree remove (git worktree unlock first if locked)

Sources: https://git-scm.com/docs/git-worktree , https://code.claude.com/docs/en/worktrees (checked 2026-10-23)

👉 Full article: https://agentkoji.com/en/articles/agent-parallel-worktree/

Top comments (0)