Run parallel agents

Run parallel agents only when the work can be split into separate reviewable branches.

Parallel work is not a badge. It is useful when each agent has its own job, branch, files, and verification path. If two agents need to edit the same code at the same time, slow down and make one of them the reviewer.

Good reasons to split work

Use separate worktrees for work like:

• Two unrelated bug fixes.
• Frontend and backend changes with a clear contract.
• A docs update while another agent works on code.
• Two alternative approaches to the same problem.
• A QA or review pass that should inspect without editing the main branch.

Do not split a task just because you can. More agents can also mean more branches to review, more failed checks, and more cleanup.

Create clear lanes

Before you launch anything, decide:

• Which task each agent owns.
• Which branch or worktree each agent uses.
• Which files each agent should avoid.
• Which commands prove each stream is done.
• Who reviews the final diff.

Write those boundaries into the task or prompt. Do not rely on the agents to infer them from your intent.

Use worktrees

A worktree is a separate checkout connected to the same Git repository. In Coldtea, a worktree lets each agent work in its own directory and branch while staying visible in the same workspace.

That separation prevents the most common collision: two agents editing the same working tree.

It does not sandbox the machine. Commands still run with local permissions, network access, and credentials available to your user account.

Launch the agents

A safe flow:

1. Break the work into reviewable units.
2. Create or open a task for each unit.
3. Start each brew in its own worktree.
4. Keep the terminal pane visible enough to catch prompts and failures.
5. Let each agent run the checks for its branch.
6. Review each diff separately.
7. Merge, continue, or discard each branch intentionally.

If one agent needs output from another, pause and pass that context explicitly. Hidden dependencies are where parallel work gets expensive.

Watch for conflicts

Parallel agents need more human coordination, not less.

Stop and adjust when:

• Two branches touch the same files.
• One agent changes shared types or generated code.
• Local services compete for the same port.
• A setup script writes machine-specific files.
• One branch invalidates the assumptions of another.

Sometimes the right move is to merge one branch first, rebase the next worktree, and continue sequentially.

Review one branch at a time

Do not review a pile of parallel output as one large blob. For each branch:

1. Read the task.
2. Read the plan and session log.
3. Inspect the diff.
4. Run the checks.
5. Decide whether that branch moves forward.

If a branch is wrong, discard it cleanly. Worktrees are cheap. Confused code is not.

Next: review agent work for the review loop.