Parallel Agents And Worktrees
Coldtea can run multiple agents side by side. The safest way to do that is to give independent streams of work their own Git worktrees.
When To Split Work
Use one stream of work when the task needs one shared branch and one review. Use multiple streams when the work can be reviewed, tested, and merged independently.
Good candidates for separate worktrees:
- Two unrelated bug fixes.
- A frontend implementation and a backend implementation with a clear contract.
- Two alternative approaches to the same problem.
- A large task that can be broken into shippable pieces.
- A QA or review agent that should inspect without editing the main branch.
Do not split work just to look busy. Parallel agents are useful only when each stream has a clear owner, branch, and verification path.
Worktree Mental Model
A worktree is a separate directory connected to the same Git repository. It has its own checked-out branch and working tree, so an agent can edit files without colliding with another active branch.
Coldtea labels worktree context in the workspace so terminal and editor surfaces stay tied to the right stream of work.
Recommended Flow
- Break the problem into reviewable units.
- Create a worktree for each unit that can move independently.
- Launch one agent per worktree.
- Keep a terminal pane available for each agent's tests or dev server.
- Review each worktree's diff separately.
- Merge or discard each branch intentionally.
- Clean up finished worktrees so the workspace stays readable.
Avoiding Conflicts
Before launching parallel agents, decide:
- Which files or modules each stream owns.
- Which branch each worktree starts from.
- Whether local services need separate ports.
- Whether each worktree needs its own local configuration, generated files, or cache.
- Which checks must pass before merging.
If two agents need to change the same files, run them sequentially or make one agent the reviewer instead of another implementer.
Setup Scripts
Some repositories need setup before a worktree can run. Coldtea can help teams run repeatable setup, run, and cleanup steps for worktrees where configured. Keep shared setup predictable, team-safe, and free of secrets or personal machine paths.
Review And Merge
Treat each worktree as a potential PR:
- Confirm the diff matches the task.
- Run the smallest meaningful checks.
- Ask an agent or teammate to review risky changes.
- Resolve conflicts before merging.
- Archive or delete the worktree only after you know whether the branch is still needed.
Tasks, Plans, And Review Flow
Coldtea keeps work close to the agent sessions that produced it. Tasks, implementation plans, and session logs help a team understand what changed and why.
Agent Context And Instructions
Good agent work starts with good context. Coldtea helps by keeping terminals, tasks, plans, session logs, annotations, and project state close together, but the most important context is still the context your team writes down.