The short version
Checked against the Orcyx source tree at c339cf993 on 2026-09-14. The steps restate the seats and swarm pages; where a step is advice rather than something Orcyx does, it says so. Where this page describes something the build does not do yet, it says so in place rather than describing the intention.
Running several AI coding agents in parallel works when each agent owns a separate task, a separate checkout and a separate branch, and when their work returns to the main branch one merge at a time. It fails when two agents share a checkout or solve the same problem. The five steps below are the order Orcyx follows for a swarm run and the order you can follow by hand with any coding CLI. Orcyx is an agentic development environment built around this loop.
Step 1: split the work into tasks that do not overlap
Give each agent one task with a clear boundary, such as one module, one endpoint or one investigation. In a swarm run the coordinator holds the plan and routes work to builders that change code, scouts that investigate and reviewers that check. By hand, you are the coordinator: write the split down before starting the agents, because two agents solving the same problem in two checkouts is a merge conflict you scheduled in advance.
Step 2: give every agent its own git worktree
One checkout shared by two agents means each reads the other's half-finished files, and a type check run by one fails on the other's in-flight edit. A separate git worktree per agent, each on its own branch, removes that shared surface at the cost of a working tree rather than a clone. Orcyx creates one for each agent pane and for each swarm role that changes code. The reasoning and the commands are in git worktrees for AI coding agents.
Step 3: make overlap visible before an agent starts
An Orcyx workspace publishes which pane is working on what, so an agent about to start a task can see that another pane already owns it and stop instead of duplicating the work. Treat that board as context, not instruction, and read it before starting rather than after. If you run agents by hand, keep the same record yourself: one line per agent naming its task.
Step 4: review what each agent returns
When a builder, scout or reviewer reports it is done, an Orcyx run lists the files that role changed and scans them for committed secrets, unsafe code patterns and content-security-policy problems before the work reaches you. The scan is advisory: it does not block, and the merge decision is yours. A scan that fails to run is reported as an error, never as a pass.
If you need something that can actually refuse a change, use the repository's pre-commit hook, which fails the commit rather than warning. Commit path-restricted, naming only the files each agent owns, so an agent's commit never captures another agent's unfinished work.
Step 5: merge one branch at a time
Each agent's work reaches the main branch by merging its branch from the main checkout. The first merge wins; every later branch rebases onto the new tip and resolves conflicts in its own worktree, never by editing the main checkout. Two agents that independently solve the same problem show up here as an add/add conflict, which is why step 1 matters.
Do not pipe the merge through another command: the pipeline reports the last command's exit status, so a merge that failed on lock contention can read as success while the merge is gone. Check that the remote branch actually moved.
Which coding CLIs this works with
Orcyx does not run models. It runs the coding CLIs you already pay for, each in its own pane on your own account, so the five steps apply to whichever you seat: Claude Code, Codex, Gemini CLI and the others on the agent integrations page. Running two different CLIs side by side is covered in Claude Code and Codex together.