Why every coding agent needs its own git worktree

The first time you run two coding agents against the same repository, it usually goes fine. The second time, one of them runs a formatter across the whole tree while the other is halfway through an edit, and you spend twenty minutes untangling a diff that belongs to nobody.

The problem is not the agents. It is that they share a working directory. Files, node_modules, build output, uncommitted changes, the branch that is checked out: all of it is global state, and agents do not coordinate.

What a worktree actually is

A git worktree is a second (or tenth) working directory attached to the same repository. Every worktree shares the object database, the history, and the remotes. Each one has its own files on disk and its own checked-out branch.

git worktree add -b feature/login-race ../login-race
git worktree list

That is the whole primitive. No clone, no second copy of history, no syncing remotes. Creating one takes about as long as checking out a branch.

One task, one branch, one worktree

Dispatcher builds on that primitive directly. When you execute a task, it:

1. Creates a branch named after the task, in the form dispatcher/task-<id>-<slug>.
2. Adds a worktree for that branch under .dispatcher/workspaces/ inside your repository.
3. Starts the agent you picked with that worktree as its working directory.
4. Keeps the terminal, the diff, and the pull request attached to the task.

Your main checkout is never touched. You can keep working in it, run your dev server from it, or start a third agent on another task while the first two are still going.

Because worktrees are just directories git already knows about, they survive restarts. If Dispatcher closes, the worktrees are still on disk and it picks them back up when it opens again.

Things that still need care

Worktrees isolate files, not everything. A few things to plan for:

• Ports. Two dev servers that both want port 3000 will still collide. Give each worktree its own port through an environment variable or a run script.
• Dependencies. Each worktree has its own node_modules (or virtualenv, or target/). The first install in a new worktree is slower; package manager caches help a lot.
• One branch per worktree. Git refuses to check out the same branch in two worktrees. That is a feature: it stops two agents from silently sharing a branch.
• Cleanup. Finished worktrees stay until you remove them. Keep them until the pull request merges in case you need to continue, then clean up with git worktree remove <path> and git worktree prune.

Why this matters more as you add agents

With one agent, a shared checkout is merely risky. With three, it is unusable. Isolation is what turns parallel agents from a source of merge conflicts into actual parallel throughput: each task moves at its own pace, gets reviewed on its own diff, and ships as its own pull request.

Everything else Dispatcher does, from side-by-side terminals to per-task review, assumes this foundation. If you only adopt one habit from agent-driven development, make it this one: never let two agents share a working directory.