Git Worktree — Agent Workspace Isolation

Agents use git worktree to safely work in parallel across multiple branches. Covers the full lifecycle of creation, switching, and cleanup, as well as concurrency safety pitfalls.

Triggers

• Agent needs to work on multiple branches simultaneously in the same repository
• Agent needs an isolated workspace to avoid polluting the main working directory
• Kanban / pipeline requires per-task independent checkouts
• User mentions "git worktree", "parallel development", "multi-branch simultaneous work"

Requirements

• Git >= 2.35 (recommended) — 2.5+ usable, 2.35+ includes fetch protection for all worktree branches
• Verify: git --version

Lifecycle

1. Create Worktree

# Standard creation (auto-creates branch with same name)
git worktree add <path> -b <branch-name>

# Agent recommended pattern: internal directory + task ID naming
WORKTREE_DIR=".worktrees/$(date +%s)-${TASK_ID}"
git worktree add "$WORKTREE_DIR" -b "wt/${TASK_ID}"

# Create from existing branch
git worktree add <path> <existing-branch>

# Detached HEAD (temporary work)
git worktree add -d <path>

2. Use Worktree

cd <worktree-path>
# Normal development...
git status
git add ...
git commit ...

3. List & Status

git worktree list                    # Human-readable
git worktree list --porcelain        # Script parsing
git worktree list --verbose          # Includes prune information

4. Lock Protection

# Lock an active worktree (prevents automatic pruning)
git worktree lock <path> --reason "active agent task TASK-123"

# Unlock
git worktree unlock <path>

5. Cleanup

# Standard cleanup (requires clean working tree + no unpushed commits)
git worktree remove <path>

# Force cleanup
git worktree remove --force <path>

# Clean up metadata (must run after manual rm -rf of directory)
git worktree prune

# Clean by expiration age
git worktree prune --expire 7.days.ago

Recommended Patterns for Agents

Per-Task Worktree (Kanban / Pipeline)

# Create
TASK_ID="t_8894c1db"
WORKTREE=".worktrees/${TASK_ID}"
git worktree add "$WORKTREE" -b "wt/${TASK_ID}"

# Clean up after task completion
git worktree remove "$WORKTREE" 2>/dev/null || {
  # Dirty worktree protection: lock + preserve
  git worktree lock "$WORKTREE" --reason "dirty: ${TASK_ID}"
  echo "WARNING: worktree $WORKTREE preserved (dirty)"
}
git worktree prune

Multi-Agent Parallel Pattern

# Agent 1
git worktree add .worktrees/agent-1 -b wt/agent-1

# Agent 2
git worktree add .worktrees/agent-2 -b wt/agent-2

# Each agent works independently in its own worktree
# Note: branch names must be unique (guaranteed by naming convention)

Concurrency Safety Rules

Pitfalls

1. Branch Name Conflict

fatal: 'wt/task-123' is already checked out by '.worktrees/task-123'

Cause: Multiple agents attempt to create a worktree with the same name from the same working directory. Solution: Include a unique ID (timestamp / task ID) in the branch name.

2. Manual rm -rf Leaves Stale Metadata

Symptom: git worktree list still shows the deleted worktree (marked as prunable). Solution: Always use git worktree remove; if already manually deleted, run git worktree prune.

3. No Remote Repository Scenario

Symptom: git worktree remove behaves differently in local repositories (never pushed). Solution: Test the no-remote scenario separately; --force may be required.

4. Relative Path Resolution

Symptom: Agent frameworks may resolve file operations to the process cwd rather than the worktree path. Solution: Use absolute paths or anchor via git worktree list --porcelain to obtain the path.

5. Stale Worktree Accumulation

Symptom: Abandoned worktrees consume disk space (100 MB–2 GB+ each). Solution: Implement a cleanup policy — skip if < 24h, delete if 24h–72h with no push, force delete if 72h+.

Configuration Recommendations

# Auto-cleanup configuration
git config gc.worktreePruneExpire 7.days.ago

# Agent environments can be more aggressive
git config gc.worktreePruneExpire 3.days.ago

Quick Reference

Sources

• Git official documentation: git worktree --help
• Hermes Agent worktree implementation (2026.03+)
• Claude Code worktree documentation: https://code.claude.com/docs/en/worktrees