Git Worktrees

Fresh

Run AI agents in parallel on separate isolated branches using Git worktrees.

Worktree Workflow

Creating a Worktree

From header:

1. Hover over the branch pill in the agent header
2. Click "Configure Worktrees"

From sidebar:

1. Right-click an agent
2. Select "Configure Worktrees"

Configuration Modal

Setting	Description
Worktree Directory	Base folder outside main repo
Watch for new worktrees	Auto-detect worktrees created outside Maestro
Create New Worktree	Enter branch name → Click Create

Worktree Display

Worktree sub-agents appear nested under parent in the Left Bar with a branch icon. A count band below the parent shows the total (e.g., "2 worktrees"). Collapse/expand by clicking the band.

Worktree Actions

Right-click a worktree agent:

Action	Description
Rename	Change the display name
Edit Agent	Modify agent settings
Duplicate	Clone the worktree setup
Create Pull Request	Auto-generate PR (requires gh CLI)
Remove Worktree	Detach but keep files
Remove and Delete	Detach and delete all files

Auto Run in Worktree

From the Auto Run configuration modal:

1. Toggle "Dispatch to a separate worktree"
2. Configure base branch and worktree branch name
3. Optionally enable auto-create PR on completion

Recommended Workflow

Use "Dispatch to Worktree" for longer Auto Runs. This isolates all changes to a branch and optionally creates a PR when done.

PR Creation

Auto-generates title and description. Source branch is the worktree branch, target is configurable.

Requires: GitHub CLI (gh) installed and authenticated.

See Also

• Parallel Development — End-to-end parallel workflow
• Auto Run & Playbooks — Dispatch Auto Run to worktrees
• Commands Cheatsheet — Git worktree commands