Git Worktrees

AgentLoop uses Git worktrees to enable real parallel development. Each worktree is a separate working directory tied to the same repository, so multiple agents can work on different branches simultaneously without stepping on each other.

What Are Worktrees?

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

Benefits

Benefit	Description
No file collisions	Each agent has its own isolated working directory
True parallelism	Multiple agents can compile, test, and modify code simultaneously
Branch isolation	Changes in one worktree don’t affect others until merged
Efficient storage	Worktrees share the same Git objects, so disk overhead is small

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

How It Works

When the orchestrator runs with worktrees enabled:

Task assignment — A task is assigned to an available agent
Worktree creation — A new worktree is created with a branch for the task
Agent execution — The agent works in the isolated worktree
Commit — Changes are committed to the task branch
Hand-off — Once the task is done, the release agent can open a PR
Merge coordination — When multiple parallel branches affect overlapping code, the merge resolver agent coordinates merging
Cleanup — Worktrees are optionally removed after completion

Configuration Options

Option	Default	Description
`use_worktrees`	`false`	Enable git worktrees for parallel development
`worktrees_dir`	`.worktrees`	Directory for worktrees (relative to project root)
`cleanup_worktrees_on_complete`	`false`	Automatically remove worktrees when tasks complete

Combining with Parallel Agents

Worktrees only really pay off when you also bump max_parallel_agents:


[orchestrator]
max_parallel_agents = 4
use_worktrees = true

With this, up to four engineer agents can work on independent tasks in parallel, each in its own worktree.

Best Practices

Use meaningful task titles — Branch names are derived from task titles
Enable auto-cleanup for short-lived work — Set cleanup_worktrees_on_complete = true if you don’t need to inspect branches after they merge
Keep worktrees for human review — Disable cleanup if you want to review agent changes before merging
Watch disk space — Multiple worktrees can consume meaningful disk for large repos (each is a full working copy)

Worktrees share Git objects, so most of the storage is cheap — but the working files themselves are duplicated per worktree.

Troubleshooting

Worktree not created

Make sure use_worktrees = true in your config
Verify your project is a git repository

Permission errors

Check that the worktrees directory is writable
Ensure git can create branches

Cleanup issues

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

Merge conflicts between parallel branches

The merge resolver agent handles most conflicts automatically
Persistent conflicts escalate to the Blocked lane for human resolution

Additional isolation with Podman containers.

Container Sandboxing

Full configuration reference.

Configuration