Two agents, one repository

What actually goes wrong#

One coding agent in a repository is a solved problem. Two is not. Both agents hold the same working tree, and neither knows the other exists: one checks out a branch while the other is mid-edit, one stages a file the other just rewrote, a test run picks up half of someone else's change. Nothing crashes — the failure is quieter and worse than that. You get a diff that no single agent intended and no one can explain.

The usual workarounds are worse than they look. Cloning the repo per agent duplicates the whole history and cuts each clone off from the others' branches. Serialising the agents throws away the reason you wanted two. Telling each agent to "only touch these files" is a rule with no enforcement behind it — the first time one of them is wrong about the boundary, you are back to the unexplainable diff.

Linked worktrees: one repository, several checkouts#

Git has had the answer since 2.5. `git worktree add` gives you another working directory backed by the same object database and the same refs — a second checkout, not a second repository. Each worktree sits on its own branch and has its own index and HEAD, so two agents editing in two worktrees cannot see each other's uncommitted work, cannot stage each other's files, and cannot move each other's branch.

What they do share is everything that is expensive to duplicate: objects, history, remotes, and every branch either of them has ever made. So the work stays mergeable. Agent A can branch from what agent B pushed an hour ago; you can review both diffs against the same base; nothing has to be reconciled across clones afterwards.

# one repository, two checkouts, two branches
git worktree add ../feature-a -b feature-a
git worktree add ../feature-b -b feature-b

# each has its own HEAD and index; the objects are shared
git worktree list

Why this is wired into sessions#

Doing the above by hand is fine for two branches and tedious for six. So in Mirasim a session can start in its own linked worktree, on a base branch you pick, and the pane you are looking at is that worktree — the file tree, the terminal, the diff and the commit you review all belong to it. Up to six panes run at once, each in its own worktree.

The part that matters in daily use is that you stop thinking about it. You are not remembering which terminal is on which branch, or which agent was told to stay out of which directory. Each pane is a place where one agent works, and the isolation is a property of the place rather than a rule the agent has to honour.

One thing worth saying plainly: parallel sessions are several agents working at once, each on its own task. They are not an orchestrator dividing one task among workers. Nothing here plans across the six panes or merges their output for you — you do that, at review time, with the diffs in front of you.