Agent fan-out and git worktrees: parallel edits without collisions

The pattern: one parent, many write-capable children

Muse Code is built around a simple rule: when a job splits into several distinct tasks, those tasks fan out automatically to separate agents. The parent agent spawns one write-capable child per task. You don’t configure this, and you don’t invoke a special parallel mode — decomposition and dispatch are the default behavior whenever the work is big enough to benefit.

The obvious question follows immediately: if several agents can write code at the same time, in the same repository, why doesn’t everything end in merge conflicts and clobbered files?

A real fan-out session: six tasks on one game, four merged, two still running — each in its own worktree under .muse/worktrees/, with the main checkout untouched.

Worktrees: isolation the git-native way

Every child agent gets its own git worktree — a separate checkout of the repository that shares history with your main copy but has its own working directory and its own branch. Two children can edit the same file in their respective worktrees without ever seeing each other’s changes mid-flight. Structurally, a collision can’t happen.

Just as important: your working copy stays clean. The directory you have open in your editor is never the one an agent is mutating. Nothing moves under your cursor, no half-finished agent edit shows up in your diff, and abandoning an agent’s work is as cheap as discarding its worktree. Changes reach your branch only when the work is done and reviewed.

Why not just branches? Or containers?

Plain branches share one working directory — switching branches mid-task would yank the rug out from under a running agent. Full containers or repo clones would work, but they’re heavyweight: duplicated object stores, slow setup, awkward merging. Worktrees hit the sweet spot. They’re near-instant to create, they share the underlying git object database, and merging a child’s finished branch back is ordinary git — no custom sync layer to trust, no proprietary state to debug.

Six features at once, demonstrably

The launch demos leaned on this mechanism hard: in the game-development example, Muse Code built six game features simultaneously, each agent in its own worktree, and every branch merged clean. That’s the practical payoff — the wall-clock time of a multi-feature sprint collapses toward the duration of its longest single task, rather than the sum of all of them.

Try the recipe

Agent fan-out is one of the three patterns Meta ships cookbook recipes for — split one big job across subagents so nothing collides mid-flight. The cookbook has the runnable version. And because fanned-out work is exactly the kind of thing you’ll want to audit later, every child’s spawn, tool call, and merge is captured in the event log — nothing happens off the record just because it happened in parallel.