Worktree Management

Advanced Git worktree techniques for multi-agent development

Overview

Advanced Git worktree techniques for multi-agent development

Master Git worktrees for efficient multi-agent development.

Git Worktrees Explained

Git worktrees allow multiple working directories to be attached to a single repository.

Key Benefits:

  • Share Git history (no duplication)
  • Independent working directories
  • Separate branches
  • Fast switching between features

Creating Worktrees

Basic Creation

# Create worktree for new branch
git worktree add -b feature/auth worktrees/agent-1 develop

# Create worktree from existing branch
git worktree add worktrees/agent-2 feature/existing

# List all worktrees
git worktree list

Automated Setup

The system provides automated tooling for worktree creation that handles:

  • Branch creation from the specified base
  • Workspace configuration and isolation
  • Dependency installation
  • Environment setup

Worktree Structure

The multi-agent system organizes worktrees in a structured hierarchy:

  • A central shared Git database serves all workspaces
  • The main worktree contains the primary codebase
  • Agent worktrees are grouped in a dedicated directory
  • Each agent workspace is a complete, isolated working copy
  • All worktrees maintain references to the shared Git database

Naming Conventions

PatternExampleUse Case
agent-N-nameagent-1-chrisAgent-specific work
feature-namefeature-authFeature development
fix-issue-Nfix-issue-123Bug fixes
experiment-nameexperiment-new-uiExperimental work

Managing Worktrees

Common Operations

# Create new worktree
git worktree add -b feature/new-feature worktrees/new-feature develop

# Navigate to worktree
cd worktrees/new-feature

# Install dependencies
pnpm install

# Start working
pnpm dev

Syncing with Develop

Keep worktrees updated with develop branch:

# In worktree
git fetch origin develop
git rebase develop

# Handle conflicts if any
git rebase --continue  # after resolving

# Or abort if needed
git rebase --abort

Worktree Lifecycle

1

Creation

Create worktree for specific task:

git worktree add -b feature/task worktrees/task develop
2

Development

Work in isolation:

cd worktrees/task
# Make changes
git commit -m "feat: implement task"
3

Push & PR

Push and create PR:

git push origin feature/task
# Create PR via GitHub or script
4

Cleanup

After PR merged:

cd ../..
git worktree remove worktrees/task
git branch -d feature/task

Advanced Techniques

Dependency Management

Each worktree can manage dependencies independently to ensure isolation. While techniques exist to share dependency installations across worktrees to save disk space, independent dependency management is generally recommended to prevent version conflicts and maintain workspace isolation.

Note:

Warning: Sharing dependencies between worktrees can cause issues if branches require different dependency versions.

Sparse Worktrees

For specialized work, Git supports sparse checkouts that only include specific directories. This technique reduces disk usage and improves performance when an agent only needs access to a subset of the codebase, such as documentation or a specific application.

Consistent Setup

The system ensures consistent worktree initialization through:

  • Standardized branch creation process
  • Automated dependency installation
  • Environment configuration templates
  • Identity and permission setup
  • Validation and verification steps

Best Practices

Note:

Worktree Best Practices:

  1. One task per worktree - Keep focused
  2. Regular cleanup - Remove unused worktrees
  3. Meaningful names - Easy to identify
  4. Sync frequently - Rebase on develop daily
  5. Independent deps - Don't share node_modules
  6. Backup work - Push branches regularly

Automation & Monitoring

The system provides comprehensive worktree management capabilities:

Automated Operations

  • Worktree creation and initialization
  • Status monitoring and reporting
  • Synchronization with main branch
  • Cleanup and maintenance

Health Monitoring

  • Real-time worktree status
  • State validation and tracking
  • Health check reporting
  • Performance metrics

Next Steps