Coding agent orchestration is the software layer that hands tasks to AI coding agents such as Claude Code, Codex or Gemini CLI, keeps parallel agents from overwriting each other, and collects their finished work for a human to review. One agent in one terminal needs none of it. You need it the day you start a second agent on the same repository.
I build PortBay, one of the tools in this category, so read the PortBay sections with that in mind. The rest of this guide describes the four architectures the category has settled into, what each one isolates, and the parts every one of them still leaves to you.
What a coding agent orchestrator does
Strip the interfaces away and every orchestrator does five jobs. The tools differ in which jobs they take on and which they leave to you.
- Dispatch. It turns a task into a running agent process with a prompt, a working directory and the right CLI flags.
- Isolation.It gives each agent a place to work where its edits can't land on top of another agent's. In 2026 that place is a git worktree in almost every tool.
- State. It tracks which agent holds which task, which tasks finished, and which ones stalled or died.
- Environment.It gives the agent something to run its change against: a dev server, a database, a URL. Most tools skip this job, and it decides whether “done” means “compiles” or “works”.
- Review. It puts the result in front of you as a diff, a pull request or a card waiting in a Review column.
Why one agent is fine and three agents collide
Run three agents in one checkout and you can watch them fight. Agent A rewrites checkout.ts while agent B is halfway through editing it. Both start npm run dev and the second one dies with EADDRINUSE: address already in use :::3000. One agent runs a migration that drops a column the other agent's test suite expects. Two of them run git commit at the same moment and one gets fatal: Unable to create '.git/index.lock': File exists.
Each of those failures has a different fix. Files need separate checkouts. Ports need separate assignments. Databases need separate schemas or separate servers. Git needs separate branches. An orchestrator earns its place by how many of those four it handles for you.
The four architectures
1. Terminal multiplexer: tmux plus a worktree per agent
The oldest pattern automates what Anthropic's own docs tell you to do by hand. Each agent gets a tmux session and a git worktree, and a terminal UI lists the sessions. Claude Squad is the reference implementation. amux pushes the same idea to dozens of unattended sessions with a web dashboard. You get the fastest path from idea to five running agents. You also keep the whole task list in your head, and the agent gets a bare checkout with nothing running in it.
2. Desktop workspace app: diff-first review
Conductor, Superset and Emdashwrap each task in a workspace (a worktree headed for a branch or PR) and build the app around reviewing what came back. Their strength is the diff view. Superset's founders put the practical ceiling at two or three complex parallel tasks, because human review runs out before compute does. Pick this shape when reviewing agent output is your bottleneck.
3. Kanban board: cards dispatch agents
Vibe Kanban, Kanbots and PortBay model work as cards. You write the task once, assign an agent, and moving the card into a column starts the run. The card keeps the state: who claimed it, what the agent said it changed, whether it passed review. Boards suit queues of small, well-specified tasks that you want to fire and come back to. They ask more of you up front, because a vague card produces a vague diff.
4. Cloud sandbox platform: agents run on someone else's machine
Warp's Oz, OpenAI's Codex cloud tasks and GitHub's Copilot coding agent run each task in a container on the vendor's infrastructure and hand you back a pull request. You get scale, with hundreds of runs at once, plus an audit trail. You give up locality: your code, secrets and test data run in their sandbox, and the environment is whatever their container image provides. PortBay vs Warp covers that trade in detail.
Side by side
| Architecture | Isolates files | Running app, DB, URL | Where state lives | Runs where |
|---|---|---|---|---|
| Terminal multiplexer | Worktree | You set them up | Your head, tmux session names | Your machine |
| Desktop workspace app | Worktree | You set them up; some tools assign ports | The app's workspace list | Your machine |
| Kanban board | Worktree | PortBay provisions them; the others leave it to you | Cards | Your machine |
| Cloud sandbox | Container | Whatever the container image holds | Vendor dashboard, PRs | Vendor cloud |
Worktrees isolate files, and that is all they isolate
Branch-based agents are the default in every local architecture above: one task, one branch, one worktree. A worktree gives the agent its own copy of the files on its own branch, sharing one .git directory. It does nothing for the processes the agent starts. Two worktrees of a Next.js app both reach for port 3000. Two worktrees of a Laravel app both read DB_DATABASE=app from a copied .env and migrate the same database.
You can fix that by hand with a port offset per worktree and a database per branch, and plenty of teams script it. The alternative is an orchestrator that owns the environment as well as the checkout. Why the environment matters more than the agent count makes the full case.
How the agent talks back to the orchestrator
An orchestrator needs to know when an agent started, what it is doing and when it finished. Tools use three channels, often more than one.
- Process exit and stdout.The terminal tools watch the process. Exit code 0 means finished. Anything richer has to be parsed out of the agent's output.
- Files on disk. The agent edits a task file and the orchestrator watches it. Any CLI that can write a file can take part.
- MCP tools. The orchestrator exposes tools over the Model Context Protocol and the agent calls them to acknowledge the task, post a comment or mark it complete. That gives you structured updates without parsing prose.
PortBay uses the second and third together. Each card is a Markdown file with YAML frontmatter at .portbay/tasks/<id>.md, and the canonical copy lives on a git ref, refs/portbay/board, so the board travels with the repo. MCP-aware agents call portbay_task_ack, portbay_task_comment and portbay_task_complete. Agents without MCP edit the file. Tasks as Markdown explains the file format.
Claims and leases: stopping two agents taking one task
Once dispatch is automatic you hit a new failure: two runs start on the same task. A double click does it. So does a second machine that shares the repo, or a retry fired while the first run is still alive. An orchestrator prevents it with a claim that expires.
In PortBay, every dispatch takes a per-project file lock, then checks two things: a local lease for the card, and the claim written into the card itself (host, run ID, timestamp). If either is live, the dispatch refuses. The agent keeps its claim alive with a heartbeat, which any authenticated MCP call refreshes. The claim goes stale after 120 seconds of silence, and a run that exceeds 30 minutes counts as a runaway.
Review caps how many agents you can run
Every architecture ends at the same place: a person reading a diff. You can start eight agents in a minute. You can't review eight nontrivial diffs in a minute, and an unreviewed merge from an agent is a bet on code nobody read. Plan your concurrency around review time, and start lower than the tools allow.
Two features cut review time more than the rest. The first is evidence before review: the agent runs the tests and checks the running app, and the card holds the result. The second is a review gate the agent can't skip. In PortBay, turning off auto-advance sends an agent's “done” into a Review column, and the move from Review to Done requires evidence on the card.
One card, start to finish
A concrete run makes the moving parts easier to see. This is what happens in PortBay with concurrency set to 2 on a git project.
- You write card 42, “Fix tax rounding at checkout”, assign Claude Code and drag it to Todo.
- PortBay takes the project lock, finds no live claim, creates a worktree at
.portbay/worktrees/42on the branchcard/42-fix-tax-rounding-at-checkout, and starts Claude Code in it. - The prompt points the agent at the project context: the app's
https://URL on its.testdomain, its ports, its runtime and the names of its database variables. - The agent calls
portbay_task_ack, makes the fix, runs the tests, loads the checkout page, comments what it changed and callsportbay_task_complete. - The card lands in Review. You open the diff tab and press Merge to main, which rebases the branch and removes the worktree. Or you press Open a pull request, which pushes the branch and runs
gh pr create.
The same card can go to Codex, Cursor, Gemini CLI, Aider, OpenCode, Amp, Qwen Code, GitHub Copilot CLI, Antigravity or a local Ollama model. Claude Code and Codex can work the same board side by side, each on its own branch.
Orchestrating coding agents vs orchestrating LLM calls
Search for “agent orchestration” and half the results cover frameworks such as LangGraph, CrewAI or the OpenAI Agents SDK. Those frameworks coordinate model calls and tools inside an application you are writing. Coding agent orchestration coordinates complete agent CLIs that each work on a repository, and the hard problems sit in git, ports, databases and review. If you want to build an agent, read the framework docs. If you want five agents to work on your codebase without trampling each other, you want one of the four architectures above.
How to choose
- You live in the terminal and want raw throughput: a multiplexer such as Claude Squad.
- Review is your bottleneck and your team works by PR: a workspace app such as Superset or Conductor.
- You want to queue tasks and come back later: a board. Pick PortBay if the tasks need a running app, a database or HTTPS to verify against.
- You need hundreds of runs, or your code already lives in the cloud: a cloud sandbox platform.
The tools also combine. Some teams run broad sweeps in a multiplexer and send the tasks that touch the database through a board. The 11 orchestrators compared covers each tool in this guide one by one.
Try the board
PortBay is free and open source (AGPL-3.0) for macOS 11+ and Linux x86_64. It provisions the runtime, a per-project database and trusted HTTPS on a .test domain, then dispatches agents from the task board into their own worktrees. Download PortBay, add a project folder, and drag your first card to Todo.
