Git Worktrees: A Workflow for Running Parallel Agents

Git worktrees isolate parallel AI coding agents into separate directories while sharing a single repository history, preventing context contamination, file overwrites, and Git lock contention. By checking out distinct branches across dedicated working directories, you allow multiple agents to run builds, execute tests, and commit changes concurrently without cloning full repositories or colliding on working trees.

The workflow at a glance

flowchart LR
  A[Ensure clean base branch] --> B[Configure directory and port isolation]
  B --> C[Create worktrees and launch agents]
  C --> D[Monitor execution across panes]
  D --> E[Review branch diffs and test results]
  E --> F[Merge branch to main]
  F --> G[Remove worktree directory]

When to use it

• Independent, parallel tasks such as adding documentation, writing unit tests, or refactoring isolated modules.
• Work where switching branches inside a single directory risks invalidating an agent's memory of the codebase.
• Setups where multiple agents must run local test suites or dev servers concurrently without lock contention.

Skip it for a single-line fix or tightly coupled changes where one agent depends on uncommitted code from another.

Step 1: Configure repository isolation

• Do: Ensure your base branch is clean, add .worktrees/ and .claude/worktrees/ to your .gitignore, and plan port allocations so running services do not collide. If using Worktrunk for orchestration, create .config/wt.toml with pre-start installation hooks and dynamic port hashing.
• Output: An updated .gitignore and an isolation configuration that assigns unique ports per branch.

Step 2: Spin up worktrees and launch agents

• Do: Create a separate worktree for each task and launch an agent inside it. For Claude Code, use native worktrees via claude -w <branch>. For orchestrated environments, run wt switch -c -x claude <branch> to set up dependencies and launch the session in one command.
• Output: Dedicated directories with checked-out branches, ready for agent execution.

Step 3: Monitor execution in isolated sessions

• Do: Provide each agent bounded instructions restricted to its target directory, following the decomposition patterns in AI Task Decomposition for Developers: A Systems Guide. Track concurrent progress across separate windows or panes using a terminal multiplexer like tmux.
• Output: Independent commits created on each branch without file conflicts.

Step 4: Review branch diffs and test passes

• Do: Inspect changes against main using git diff main..<branch> and run your test suite inside the worktree before approving any merge.
• Output: Verified commits that meet your review criteria.

Step 5: Merge and prune the worktrees

• Do: Merge the feature branch into main, then delete the worktree directory to prevent accumulating unused files on disk. With native tools, remove the directory when prompted on exit; with Worktrunk, run wt merge main or clean up merged trees with wt step prune.
• Output: Merged code on main and clean disk storage.

Variations

• Manager and subagents: Use a lead agent to delegate bounded subtasks to parallel worktree sessions, following the structure in Manager and Subagents: A Workflow for Repetitive Tasks.
• Structured review cycles: Combine worktree isolation with the multi-stage review loop in Spec, Plan, Build, Review: A Workflow for Agent Coding by spinning up a reviewer agent in a read-only worktree.
• Manual Git: If avoiding extra tools or CLI wrappers, create worktrees directly with git worktree add ../feature-branch feature-branch and remove them with git worktree remove.

Frequently asked questions

Why use Git worktrees instead of multiple repository clones?

Worktrees share the .git storage directory of the primary repository, avoiding duplicated history and saving disk space. Git operations like fetching remain centralized, while working files and branches remain isolated.

How do parallel agents avoid local port collisions?

Assign dynamic ports based on branch names. Tools like Worktrunk automate this through templates like {{ branch | hash_port }}, ensuring that background dev servers or mock APIs run on unique ports without manual configuration.

What happens if the base branch has uncommitted changes?

Creating a worktree from a dirty tree can carry uncommitted changes into the new directory or fail during checkout. Run git status and commit or stash changes before creating new worktrees.