AO
PluginsWorkspacesworktree

worktree

Default workspace. Each session is a git worktree pointing at a fresh branch.

Slot: workspace · Name: worktree

The default workspace plugin. Each session gets a git worktree with its own branch. All worktrees share the underlying .git object database, so disk usage stays low even with dozens of parallel agents.

macOSSupported
LinuxSupported
WindowsSupported

Use

agent-orchestrator.yaml
workspace: worktree
workspaceConfig:
  worktreeDir: ~/.worktrees     # default
Config keyDefaultWhat it does
worktreeDir~/.worktreesBase directory for all worktrees

How it works

  • On spawn, AO runs git worktree add <worktreeDir>/{sessionId} -b <branch> against the project's upstream.
  • The agent works inside that worktree. Commits land on its dedicated branch.
  • On cleanup, AO runs git worktree remove and prunes the branch if it was never pushed.

Per-project knobs

projects:
  api:
    repo: myorg/api
    workspace: worktree
    symlinks:
      - .env.local
      - node_modules
    postCreate:
      - pnpm install
KnobPurpose
symlinksFiles/dirs to symlink from the source repo into each worktree (e.g. .env.local, a shared cache)
postCreateShell commands to run in each new worktree after creation (e.g. pnpm install)

Troubleshooting

  • "fatal: working tree already exists". A previous session didn't clean up. ao session cleanup or manually git worktree remove --force <path>.
  • Branch protection rejects the agent's push. Expected — the agent pushes its own branch, not to your protected main.
Edit on GitHub

Workspaces overview

How each agent gets its own copy of the repo — a git worktree or a full clone.

clone

Full per-session git clone. Use when worktrees fight your tooling.

On this page

Use
How it works
Per-project knobs
Troubleshooting