Git Worktrees for Parallel AI Development

What Are Git Worktrees

A git worktree is an additional working directory linked to your repository. Instead of cloning a repo multiple times (duplicating the entire .git directory each time), worktrees share the same git object database while each having their own checked-out branch and working files.

git worktree add ../my-repo-feature-branch feature-branch

This creates a new directory with feature-branch checked out, linked to the original repo. Changes in either worktree are visible to git, and you can commit, push, and pull from any of them independently.

Why Worktrees Matter for AI Agents

When you run multiple AI agents on the same project, each agent needs its own working directory. Without worktrees, you either:

• Clone the repo multiple times, wasting disk space and creating disconnected git histories
• Have agents share a single checkout, leading to merge conflicts and corrupted state
• Stash and switch branches constantly, losing context

Worktrees solve this cleanly. Each agent gets its own branch and its own directory. They share git history, so changes from one agent are immediately visible (as commits) to the others.

The Bare Repo Pattern

For the best experience with multiple worktrees, aoe supports the bare repo pattern. Instead of having a "main" clone with worktrees branching off it, you start with a bare repository (no working directory) and create all checkouts as worktrees.

The recommended layout nests the bare object store and all worktrees under a single parent directory:

mkdir repo && cd repo
git clone --bare git@github.com:user/repo.git .bare
echo "gitdir: ./.bare" > .git
git worktree add main main
git worktree add feature feature

This produces a clean structure where everything lives under one directory:

repo/
  .bare/        # shared git object store
  .git          # file pointing to .bare
  main/         # worktree on main branch
  feature/      # worktree on feature branch

All worktrees are equal peers, and the bare repo is just the shared object store. There is no "special" main directory. aoe automates this setup for you.

How aoe Automates Worktrees

When you add a session in Agent of Empires with worktree mode enabled, aoe handles the full lifecycle:

1. Creates the worktree from your configured base repository
2. Checks out the branch you specify (or creates a new one)
3. Points the agent's session at the worktree directory
4. Cleans up the worktree when the session is removed

Combined with Docker sandboxing, each agent gets its own isolated branch in its own container. This is the most robust setup for parallel AI development.

Daily Workflow

A typical day with worktree-based AI development looks like:

1. Open aoe and review your agent sessions in the TUI dashboard
2. Add a new session for a feature branch: the worktree is created automatically
3. Start your AI agent in the session and give it the task
4. Meanwhile, another agent is working on a different branch in a different worktree
5. Review and merge completed work from any worktree
6. Remove finished sessions, and aoe cleans up the worktrees

Getting Started

Enable worktree mode in the aoe settings and configure your base repository. See the worktrees reference for detailed setup instructions.