Worktree Isolation

Worktree isolation gives each spawned sub-agent its own git worktree branch and working tree, preventing concurrent agents from conflicting on the same files and making it easy to review or discard work per-agent.

Requirement: Requires a git repository with at least one existing commit.

Enable per-call

Pass worktree: true to spawn_agent:

spawn_agent(
  prompt="Refactor the auth module",
  worktree=True
)

The response includes:

• worktree_path — absolute path to the isolated working tree
• worktree_branch — name of the git branch created for this agent

Enable globally

Enable worktree isolation for all spawned agents in your config:

[agents.task.delegation]
worktree_isolation = true
worktree_auto_remove = false

Option	Default	Description
worktree_isolation	false	Create a git worktree per spawned sub-agent
worktree_auto_remove	false	Delete the worktree and branch when the agent finishes; false keeps the branch for manual review

Reviewing and merging

When worktree_auto_remove = false (default), each finished agent’s branch is kept:

git log --oneline feature/agent-auth-refactor
git diff main..feature/agent-auth-refactor
git merge feature/agent-auth-refactor

Use /worktree in the TUI to inspect discovered worktrees, remove preserved BMO-managed sub-agent worktrees, prune stale worktree metadata, and toggle the next-spawn isolation and auto-remove overrides without leaving BMO.

Discarding work

To discard a worktree and its branch:

git worktree remove /path/to/worktree
git branch -D feature/agent-auth-refactor

Related

• Multi-Agent & Teams — spawning, teams, and CSV fan-out patterns
• Workflow map — how worktree isolation fits with other runtime coordination layers