Coordinate parallel coding agents with git worktrees

Start with one acceptance contract

Parallel coding agents need a shared task definition and separate scopes. A useful plan says what changes, what must stay compatible, which files are shared, which tasks depend on others and how the final result will be checked.

AiOrch proposes agent tasks from the overall objective and project context. With plan auto-approval disabled, you can inspect and adjust that decomposition before implementation begins.

Separate responsibilities before branches

For an illustrative retry-delay change, a plan could divide implementation, boundary tests and documentation. Define the public behavior once, then give each task clear acceptance criteria. If the test task depends on the new API, capture that dependency rather than asking every agent to invent it independently.

Two agents editing the same file can still be appropriate, but call that overlap out in the plan. Increasing the agent count without separating responsibilities can increase review and integration work.

Use worktrees to separate working copies

A git worktree lets each agent work in a separate checkout and branch while sharing the repository’s Git history. This keeps uncommitted edits from several agents out of a single working directory.

In AiOrch, agents work in assigned worktrees and their branches can later be combined into an integration branch. A worktree is an organizational boundary; accessible filesystem permissions and mounts still determine what an agent process can reach.

Read the agent boundary guidance before enabling headless execution. Keep unrelated repositories and credentials outside the accessible project tree.

Order dependencies and limit concurrency

Independent tasks can run in parallel. Tasks that consume another task’s interface or result should depend on it. Larger multi-phase changes can use pipelines so later phases follow the earlier work.

The parallel-agent limit controls simultaneous work; provider rate limits, host memory, build processes and model usage also constrain throughput. Begin conservatively and observe a real run before expanding concurrency.

You can assign separate planning, implementation and review models. Difficulty-based routing can use different configured implementation models for different tasks. See the provider configuration guide.

Review the combined result

Agent review happens before the configured branch-integration step. Integration can expose common-file conflicts or behavior that no individual branch revealed. Conflict-resolution work does not remove the need to validate the combined branch.

Configure the repository’s actual check through integration_test_command when appropriate. Otherwise, understand which detected gates ran. A missing toolchain can produce an unverified advisory result; strict policy blocks that delivery.

Enable GitHub PR creation when you want that handoff and configure access to the repository. Your team reviews the integrated diff and validation history before merging.

Evaluate the workflow on one real task

Record the task, base revision, provider/model configuration, agent count, elapsed time, revisions, conflicts, checks and human intervention. Compare with your existing process only when those conditions are understood.

Do not infer a general speedup from a single task or treat estimated CLI usage as a complete inference bill. A useful evaluation shows both the work the orchestrator handled and the work your team still needed to do.

To try this on your own repository, follow the installation and first-session guide. For the full delivery policy, read review and validation.