Git Worktree

A git worktree is an additional working directory that is linked to an existing git repository. It allows you to have multiple branches checked out at the same time in different directories, each with its own working copy of the code.

Why worktrees matter for AI agents

When multiple AI agents work on the same codebase simultaneously, they need isolation. Without it, Agent A editing a file while Agent B edits the same file causes conflicts, overwrites, and lost work.

Worktrees solve this by giving each agent its own directory with its own branch. Both agents read and write files independently. When they finish, their branches are merged back into the main repository.

How worktrees work

A standard git repository has one working directory (your project folder) checked out to one branch. A worktree adds another working directory, checked out to a different branch, but sharing the same git history and objects.

Key properties: - Each worktree has its own branch (you cannot check out the same branch in two worktrees) - All worktrees share the same git history and configuration - Changes in one worktree do not affect others until merged - Worktrees are lightweight — they share the git object database, so they do not duplicate the full repository

Practical commands

• Create a worktree: `git worktree add ../my-feature feature-branch` — creates a new directory with the feature branch checked out
• List worktrees: `git worktree list` — shows all active worktrees
• Remove a worktree: `git worktree remove ../my-feature` — cleans up when done

In multi-agent workflows

The typical pattern for agent-parallel development: 1. Create a worktree for each agent (or let the orchestrator create them) 2. Each agent works in its own worktree on its own branch 3. When agents complete, review their changes on each branch 4. Merge branches back into main, resolving any conflicts

In Claude Code, you can spawn agents with `isolation: "worktree"` and the worktree is created and managed automatically. If the agent makes changes, you get back the branch name. If it makes no changes, the worktree is cleaned up.

When to use worktrees

Worktrees add value when agents edit the same codebase in parallel. For agents that only read code (research, analysis) or that work sequentially (one finishes before the next starts), worktrees are unnecessary overhead.