Multi-agent orchestration for coding agents: a practical guide

What is multi-agent orchestration?#

Multi-agent orchestration is the work of getting several AI agents to act as one team: deciding who does what, passing work and context between them, collecting their results and stepping in when one of them needs a person. For coding agents, that means Claude Code, Codex, Gemini CLI, Grok or OpenCode each working on part of a change while something coordinates the hand-offs.

Without orchestration, you are the orchestrator. You copy a plan out of one terminal and paste it into another, you relay a reviewer's comments back to the agent that wrote the code, and you keep a mental map of which tab is doing what. It works for two agents. With four, most of your day becomes moving text between windows.

Orchestration replaces that clipboard work with explicit structure: which agents exist, which ones may talk to each other, what each one is responsible for, and where the results go. The agents still do the coding. The orchestration layer makes the team visible and lets them reach each other directly.

Why use more than one coding agent?#

A single strong agent is enough for a lot of tasks. A team earns its keep when the work has distinct roles or can run in parallel:

• Different strengths. One model plans well, another writes tests quickly, a third is a careful reviewer. Using each where it is best usually beats asking one model to do everything.
• A second opinion. A reviewer agent from a different provider catches mistakes the author agent is blind to, because it did not write the code.
• Parallel work. Independent tasks (a migration, the tests for it, the docs) finish sooner when three agents run them at once on separate branches.
• Separate context. Each agent keeps a focused context window instead of one conversation that has to hold the whole project.

The cost is coordination. Every extra agent is another place where work can stall, collide or get lost, which is exactly what orchestration is for.

Multi-agent patterns that work for code#

Most useful setups are one of a handful of shapes. Start with the simplest one that fits the task.

Orchestrator and workers

One agent takes the request, splits it into tasks and hands each to a worker: “Codex, write the endpoint; Gemini, write its tests.” Workers report back and the orchestrator assembles the result. This is the default shape for a feature that has several parts.

Author and reviewer loop

One agent writes, another reviews, and the author fixes what the reviewer found, repeating until the reviewer is satisfied. Using models from two providers makes the review more independent.

Parallel branches

Several agents work at the same time on separate copies of the repository, so they never edit the same file under each other. You review each branch and merge the ones that are good. This is the pattern that turns three agents into three times the throughput rather than three times the conflicts.

Pipeline

Work flows through stages in order: plan, implement, test, document. Each stage is an agent with one job and its output is the next stage's input.

Shared notes

Agents read and append to the same notes (a specification, a progress log, a decision record) instead of repeating context in every message. The note becomes the team's memory.

What a multi-agent setup needs#

Whatever tool you use, a team of coding agents needs the same parts:

1. 1Real sessions. Each agent runs its own CLI on its own login, model and settings, so it behaves exactly as it does in your terminal.
2. 2Addressing. An agent can find the agents it is allowed to work with and send one of them a task.
3. 3Results that come back. A task has an id, a sender and a recipient, and its result returns to whoever asked, rather than being typed into a terminal and hoped for.
4. 4Permission boundaries. Agents only reach the agents, notes and tools they have been given, so a worker cannot wander into unrelated work.
5. 5Isolation. Parallel agents work on separate branches, so their edits cannot collide.
6. 6Attention. When an agent finishes, fails or asks for approval, you find out without checking every window.
7. 7Review. You can see what each agent changed and decide what lands.

How MAO orchestrates coding agents#

MAO is a desktop app for multi-agent orchestration of coding agents. It puts each agent on an infinite canvas as a real terminal and turns the parts above into things you can see and draw.

• Every agent is its real CLI. A node runs Claude Code, Codex, Gemini CLI, Grok, OpenCode, Antigravity or a plain shell, on that agent's own login and model. MAO does not proxy or replace the agent.
• A wire is a permission. Drawing a connection between two agents lets them find each other and exchange tasks. Wiring an agent to a note lets it read and append to that note. Nothing else is reachable.
• Agents talk through the mao command. Inside its terminal an agent can list its peers, send a task, wait for the result and read or update a connected note.
• An Orchestrator can staff the canvas. Mark one agent as the Orchestrator and it can recruit new agents, connect them and hand out work, so you describe the goal once.
• Layers are git worktrees. Each layer is a real branch in its own working tree, so parallel agents never edit the same checkout. You review the diff on the canvas and land the layer when it is ready.
• Attention finds you. An agent that finishes, fails or rings for you shows it on its node and in a desktop notification.

A worker that needs a reviewer simply asks it, from its own terminal:

mao peers
mao ask reviewer "Review the session refresh changes on this branch"
mao note append progress "Refresh path done; reviewer is on it"

mao ask sends the task and waits for the answer; mao send returns a task id at once, and mao wait collects its result later. The result is routed back to the agent that asked, and tasks survive an app restart.

Set up a team of agents in five minutes#

1. 1Download MAO for macOS, Windows or Linux and open your repository as a workspace.
2. 2Place your agents. Add a node for each agent you want (for example Claude Code to plan, Codex to build and Gemini to review). Each one starts its own CLI on your existing login.
3. 3Draw the wires. Connect the planner to the builder and the builder to the reviewer. Add a note for the specification and wire it to all three.
4. 4Pick an Orchestrator. Mark the planner as the Orchestrator so it can hand out work and recruit help if the task grows.
5. 5Give each agent a layer when they will edit code in parallel, so each works on its own branch.
6. 6Ask once. Tell the Orchestrator what you want. Step in when an agent asks for approval, then review the diffs and land what is good.

Multi-agent frameworks vs an orchestration app#

Two kinds of tools come up when you search for multi-agent orchestration, and they solve different problems.

If you are building an AI product, a framework is the right tool. If you want the coding agents on your machine to work together on your repository, an orchestration app is.

Tips for teams of coding agents#

• Give each agent one job. A role such as “reviewer: point out bugs and missing tests, do not edit files” keeps it focused.
• Keep shared context in notes, not in messages. A specification note every agent can read prevents drift.
• Isolate parallel work. Two agents editing the same checkout is the most common way a multi-agent session goes wrong; separate branches prevent it.
• Mix providers for review. A reviewer from a different model family catches more than one from the same family.
• Start small. Two agents and one wire teach you more than a team of eight on day one.

Frequently asked questions#