Worktree Isolation: Parallel Tasks Without Conflicts

SuperBuilder runs each AI agent in its own isolated git worktree. Every task gets a dedicated branch and workspace — agents work in parallel without interfering with each other or with your working directory.

What Is a Git Worktree?

A git worktree is an additional working directory linked to the same repository. It's like having multiple checkouts of the same repo, but without the overhead of duplicating the entire .git directory. Each worktree can be on a different branch, and changes in one worktree don't affect others.

SuperBuilder creates a worktree automatically for each agent task. The agent works in its worktree, on its branch, completely isolated from:

• Your main working directory (you can keep coding while the agent works)
• Other agents running in parallel (each has their own branch)
• Any in-progress changes you haven't committed

Running Tasks in Parallel

Without worktree isolation, running multiple agents would cause chaos — they'd read and write the same files, step on each other's changes, and produce unpredictable results.

With worktrees, you can run 5 agents simultaneously with no conflicts:

• Agent 1: refactoring the auth module on branch agent/refactor-auth
• Agent 2: writing tests for the payment system on branch agent/test-payments
• Agent 3: fixing a CSS layout bug on branch agent/fix-layout-bug
• Agent 4: updating API documentation on branch agent/docs-api
• Agent 5: investigating a performance issue on branch agent/perf-investigation

They all run at the same time. You review the results and merge what you want.

Your Working Directory is Always Safe

When an agent is working in a worktree, your main working directory is untouched. You can:

• Keep coding in your editor without seeing the agent's in-progress changes
• Commit your own work normally
• Switch branches in your main working directory

The agent's work is invisible to you until it's done and you choose to review it.

Reviewing Agent Work

When an agent finishes a task:

1. SuperBuilder shows you a summary of what changed
2. You can open a diff view to see every file modification
3. You can open the worktree in your editor to explore the changes in context
4. You can approve (merge) or discard the changes with one click
5. Approved changes merge to your target branch via a standard git merge

You're always in control of what gets merged. Nothing goes to your main branch automatically.

The Branch Battle Connection

Worktree isolation is what makes Branch Battle work. Both agents run in separate worktrees on separate branches — completely independent work that you compare side by side when they're done.

Without worktrees, parallel agents would be impossible. With them, it's the natural way to work.

Automatic Cleanup

After you review and either merge or discard an agent's work, the worktree is cleaned up automatically. You don't accumulate a bunch of stale branches and directories. The worktree is created for the task and removed when you're done with it.

You can also configure how long to keep worktrees before auto-cleanup — some people like to keep them around for a few days in case they want to go back.

How Isolation Protects You

No accidental overwrites — an agent can't accidentally overwrite a file you're actively editing, because it's working in a completely different directory.

Reversible by default — since all agent work is on a separate branch, you can discard any agent's changes instantly with zero impact on your codebase.

Git history is clean — when you merge an agent's work, it goes through a normal git merge. Your commit history reflects real changes with real commit messages.

Concurrent feedback — you can give feedback to one agent while another is still working, without either interfering with the other.

Frequently Asked Questions

How many worktrees can run at once?

There's no hard limit in SuperBuilder, but practically your machine's resources (RAM, CPU) determine how many parallel agents are comfortable. Most developers run 3-5 in parallel.

Does the agent get a fresh copy of the repo each time?

No — worktrees share the git object store with your main repo, so creation is fast. The agent starts from whatever branch you configure as the base (usually your main branch or the current branch).

What if two agents modify the same file?

They work in separate worktrees, so they each have their own copy. When you merge, you'll resolve conflicts the same way you would with any two branches that touched the same file. SuperBuilder highlights when worktrees have overlapping changes before you merge.

Can I see what branch an agent is working on?

Yes. Each active agent task shows its branch name in the thread view. You can also list all active worktrees in the sidebar.

Can I continue an agent's work after it finishes?

Yes. You can open a new thread pointing at the agent's worktree branch and continue from where it left off.