Run parallel agents

Run parallel agents when the work splits into separate reviewable branches. In Coldtea, each branch gets its own worktree: a separate checkout that stays visible in the same workspace.

Parallel work is not a badge. It helps 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.

When you want many agents going at once without your machine carrying all of them, move the work to cloud runs so each runs on its own hosted pane.

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 base branch.

Do not split a task just because you can. More agents also means 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.

Start a worktree

Press Cmd+Y (Ctrl+Y on Windows and Linux) to start a worktree from the active pane. You can also right-click the pane and choose "Start worktree from this pane". Coldtea creates the worktree from a selected base branch, or from the current commit in a detached-HEAD case, and the start modal previews the derived worktree name and branch before anything launches.

For a batch of tasks, Coldtea can create one worktree per task, each with its own generated name so the sessions do not pile into the same directory.

Check the base branch before you confirm. A worktree created from the wrong branch is still a wrong branch.

Configure scripts

Worktree scripts are optional. When configured, Coldtea runs setup after creating a worktree, runs a project command from the worktree, and runs teardown before deletion. Open the scripts settings with Cmd+Shift+Y (Ctrl+Shift+Y on Windows and Linux).

Scripts run in visible panes. If a setup script fails, inspect it before handing the worktree to an agent. Shared scripts live in .coldtea/config.json; per-machine overrides live in .coldtea/config.local.json. See worktree scripts for the full setup.

Worktree lifecycle

A worktree tab shows a banner with the base project, base branch, worktree branch, and script status. Use it to answer "where am I?" before prompting an agent. From the pane's right-click menu you can:

• Reveal worktree folder: open the worktree directory in your OS file manager.
• Open base project tab: open a terminal tab rooted at the base project.
• Copy local-only files from base project: bring untracked and ignored files into the worktree.
• Finish worktree: review branch status before you decide what to do next.
• Delete worktree: remove the worktree directory and unregister it.

Copy local-only files

Some repos need files that Git does not track: local .env files, generated config, or ignored settings. This action scans the base project for untracked and ignored entries, then shows a checkbox list so you choose what to copy into the worktree. Files with the same name are overwritten. Be selective: copy what the worktree needs, not every private file you have.

Finish or delete

Finishing a worktree is a review moment. Coldtea can show branch status and uncommitted changes before you decide. Deleting removes the worktree directory and unregisters it, then attempts best-effort cleanup of the linked branch. The base project stays untouched. Untracked local files are not covered by the uncommitted-changes guard, so check anything local-only before you delete.

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.

What worktrees do not isolate

A worktree separates Git working directories. It does not isolate machine permissions, credentials, local services, package caches, or databases. Commands still run with the permissions of your user account.

Use worktrees to keep branches from stepping on each other. Do not treat them like containers. For the concept, see worktrees.

Next: review agent work for the per-branch review loop.