Git Worktrees

AgentLoop leverages Git worktrees to enable true parallel development. Each worktree is a separate working directory linked to the same repository, allowing multiple agents to work on different branches simultaneously without conflicts.

What Are Worktrees?

Git worktrees allow you to have multiple working directories from a single repository. Each worktree has its own branch, but they all share the same Git history and objects.

Main Repository (.git)
        │
        ├── Main Working Directory (main branch)
        │
        ├── .worktrees/
        │       ├── feature-auth/     ← Agent 1 working here
        │       │   └── (branch: feature/auth)
        │       │
        │       ├── feature-api/      ← Agent 2 working here
        │       │   └── (branch: feature/api)
        │       │
        │       └── bugfix-login/     ← Agent 3 working here
        │           └── (branch: bugfix/login)

Benefits

Enabling Worktrees

Configure worktrees in your project config:

[orchestrator]
use_worktrees = true
worktrees_dir = ".worktrees"   # Directory for worktrees (relative to project)
cleanup_worktrees_on_complete = false  # Auto-cleanup when tasks complete

Or set via environment variables:

export AGENTLOOP_USE_WORKTREES=true
export AGENTLOOP_WORKTREES_DIR=".worktrees"
export AGENTLOOP_CLEANUP_WORKTREES=false

Worktree Commands

agentloop orchestrator

How It Works

When the orchestrator runs with worktrees enabled:

1. Task Assignment - A task is assigned to an available agent
2. Worktree Creation - A new worktree is created with a branch for the task
3. Agent Execution - The agent works in the isolated worktree
4. Commit & Push - Changes are committed to the task branch
5. PR Creation - A pull request is created (if configured)
6. Cleanup - Worktree is optionally removed after completion

Configuration Options

Example Workflow

# Enable worktrees in config
> /config show

# Start orchestrator with multiple parallel agents
> /orchestrator run

# The orchestrator will:
# 1. Pick up 3 independent tasks
# 2. Create 3 worktrees (one per task)
# 3. Assign an engineer agent to each
# 4. Process tasks in parallel

# View active worktrees
> /worktrees list

# Output:
# .worktrees/feature-auth (branch: feature/auth) - Task 3
# .worktrees/feature-api (branch: feature/api) - Task 4
# .worktrees/bugfix-login (branch: bugfix/login) - Task 5

Remote Development

Worktrees are particularly useful for remote development scenarios:

1. SSH into a server
2. Start the orchestrator with worktrees enabled
3. Disconnect and reconnect later
4. Work directly on mounted worktrees from your local IDE

This allows you to edit code locally while agents work remotely.

Best Practices

• Use meaningful branch names - Worktrees create branches based on task names
• Enable auto-cleanup for temporary work - Set cleanup_worktrees_on_complete = true for short-lived tasks
• Keep worktrees for code review - Disable cleanup to review agent changes before merging
• Monitor disk space - Multiple worktrees can consume significant disk space for large repos

Troubleshooting

Worktree not created:

• Ensure use_worktrees = true in your config
• Verify you’re in a git repository

Permission errors:

• Check that the worktrees directory is writable
• Ensure git has access to create branches

Cleanup issues:

• Manually remove worktrees: git worktree remove .worktrees/<name>
• List all worktrees: git worktree list