Agent Orchestration: How to Run a Team of Coding Agents
What a control plane for coding agents has to do, how it differs from LangGraph-style frameworks, and when one agent is enough.
Last updated · By Adel Ahmadyan
Agent orchestration, in software development, is the layer that assigns work to coding agents such as Claude Code and Codex, runs each one in an isolated workspace, tracks which ones need a person, and moves their output through review to a merged pull request. It is a different job from agent orchestration frameworks like LangGraph or CrewAI, which developers use to build agents into their own applications. With one provider, the orchestration built into Claude Code or Codex is enough to start. With several providers, containers, remote hosts, or standing automation on a Mac, use a control plane such as Agentastic.
Our orchestration tools roundup compares Agentastic with Paseo, Orca, Superset, Conductor, and others. This guide covers what any of them has to do, and when you can skip them.
Coding-agent orchestration at a glance#
Every orchestrator, whether it is a person, a script, or another agent, has to answer the same eight questions. These are the primitives.
| Primitive | The question it answers | How Agentastic answers it |
|---|---|---|
| Isolation | Where can this agent write? | Worktree, Docker or Apple container, SSH host, or cloud VM per task |
| Environment | Will a fresh checkout build and run? | Setup and teardown scripts per worktree or container |
| Sessions | Which task owns this agent, and can I pick it up later? | Agents bound to worktrees, session IDs, idempotent launch receipts |
| Attention | Who needs me right now? | Notification inbox, Shift-Command-U, Kanban board, iPhone Companion |
| Review | Does it work, and should it merge? | Diffs, browser checks, AI code review, pull requests |
| Triggers | What starts work without me? | Schedules, Linear and Sentry issues, Slack, Manager Agent heartbeats |
| Control | Can a script or another agent drive this? | The dev CLI and its JSON-RPC socket |
| Memory | What will the next run know? | Task memory documents, a Manager Agent's git-backed wiki |
What AI agent orchestration means for coding#
Running one agent in one terminal is not orchestration. Orchestration starts when coordinating the agents becomes a job of its own: deciding who works on what, keeping them out of each other's files, noticing when one is stuck, and choosing what merges.
Three kinds of orchestrator can do that job. You can do it from a UI, dispatching tasks and reviewing results. A script can do it through a CLI, on a schedule or in CI. Or another agent can do it, planning the work and starting workers. A good control plane supports all three with the same primitives, so you can start by hand and automate one step at a time.
Orchestration vs harness vs choreography#
Three neighboring terms get mixed up. A harness is the runtime around a single agent: its loop, tools, prompts, and permissions. Claude Code and the Codex CLI are harnesses. Orchestration coordinates many harnessed agents from a center, whether that center is you, a script, or a lead agent. Choreography has no center: agents coordinate through shared state. Claude Code's agent teams mix the two, with a lead that assigns work and teammates that share a task list and message each other directly. For code that has to merge, a center and a person who owns the result remain the safer default.
Agent orchestration frameworks vs coding-agent orchestration#
Search for "agent orchestration framework" and you will find libraries for building agents into software. LangChain describes LangGraph as "a low-level orchestration framework and runtime for building, managing, and deploying long-running, stateful agents." CrewAI orchestrates role-playing agent crews, the OpenAI Agents SDK targets multi-agent workflows, and the Microsoft Agent Framework builds, orchestrates, and deploys agents in Python and .NET.
Those tools solve a different problem from the one in this guide.
| Agent orchestration framework | Coding-agent orchestration | |
|---|---|---|
| What you get | A library or runtime you build on | A workspace or CLI you operate |
| Examples | LangGraph, CrewAI, OpenAI Agents SDK, Microsoft Agent Framework | Agentastic, Claude Code agent teams, Codex subagents |
| The agents | Ones you write | Existing coding agents such as Claude Code, Codex, and Gemini CLI |
| Unit of work | A request moving through a graph or crew | A task on a repository |
| Output | An answer or action inside your product | A diff and a pull request |
| Where state lives | Checkpoints and memory stores | Branches, worktrees, and session transcripts |
| How work is checked | Evals, guardrails, and tracing | Tests, review, CI, and a person |
Plenty of teams use both: a framework to put an agent inside the product, and a coding-agent orchestrator to build the product.
The primitives of coding-agent orchestration#
Isolation#
Each editable task needs its own checkout, or two agents will overwrite each other's files and build output. A Git worktree is the minimum. Worktrees isolate files, not processes, ports, credentials, or services, so tasks that touch those need a container, a remote machine, or a cloud VM. In Agentastic you choose per task, in Agent Home or with dev agent create --mode.
Environment#
An agent dropped into a bare checkout spends its first minutes, and your tokens, working out how to install dependencies. A setup script fixes that. Agentastic runs .agentastic/setup.sh whenever it creates a worktree or container, with the branch and paths in environment variables. See setup and teardown scripts.
Sessions#
The orchestrator has to know which task owns which agent, and find it again after a restart. Agentastic binds each agent to its worktree and gives native chats a session ID you can query with dev agent status and dev agent tail. Launches accept a --request-id, so a retried create returns the original worker instead of starting a second one. Remote SSH sessions keep running when the Mac sleeps.
Attention#
Ten running agents produce a lot of terminal output and very few decisions. The orchestrator should surface only the decisions. Agentastic keeps a durable notification inbox that separates finished, blocked, and failed agents, and Shift-Command-U jumps to the next one that needs you. The Kanban board shows every worktree with diff stats, PR status, and a live peek at its terminal. The Companion iPhone app, a TestFlight beta, lets you answer from your phone.
Review#
The output of a coding agent is a diff, not a transcript. Agentastic attaches review to the task: a diff viewer with guided chapters for large changes, a browser the agent can drive with dev browser, AI code review from a different provider than the one that wrote the code, and pull requests you can check and merge in the app.
Triggers#
Some work should start without you: a nightly bug hunt, a new Sentry error, a Slack request. Agentastic supports schedules, Linear and Sentry issues, Slack mentions and DMs, and Manager Agent heartbeats. Local runs need the app open and the Mac awake; tasks scheduled on an SSH host run there even while the Mac sleeps.
Control#
If a script or another agent cannot drive it, it is a dashboard, not an orchestrator. The system-wide dev CLI talks to the running app over a local JSON-RPC socket, with --json output and stable exit codes for cron jobs, CI runners, and bots. The programmatic control guide has recipes.
Memory#
LLMs don't remember the last run, so the orchestrator has to. Each scheduled agent owns memory documents stored outside the repository, so tomorrow's bug hunt skips what today's already triaged. A Manager Agent keeps its notes in a wiki inside a git repository it owns.
Agent orchestration patterns#
| Pattern | Shape | Use it for | In Agentastic |
|---|---|---|---|
| Fan-out | One task, several agents, keep one result | Uncertain approaches, risky fixes | Multi-instance launch from Agent Home |
| Split | One feature, several independent tasks | Work that separates cleanly | One worktree and label per task |
| Pipeline | Implement, then review, then verify | Quality gates | Review agents, worktree relationships |
| Manager–worker | An orchestrator agent delegates and follows up | Long-running streams of work | Manager Agents |
| Scheduled maintenance | Recurring runs with memory | Chores nobody schedules | Scheduled agents |
| Issue intake | Work arrives from trackers and chat | Bugs, errors, requests | Linear, Sentry, Slack |
Fan-out#
Send the same task to several agents and keep the best result. In Agent Home you can select several agents and set instance counts, say Claude Code twice and Codex once, and each instance gets its own worktree. Agents launched together are linked as a group on the Kanban board, which makes the comparison easy.
Split#
Break a feature into tasks that can land independently, such as an API, its UI, and its tests, and give each its own agent and worktree. Labels put each run in the right Kanban column the moment it starts. Keep work sequential when two tasks touch the same central type or a migration that the rest depends on.
Pipeline#
Chain stages so each one checks the last. One agent implements, a second agent from a different provider reviews the diff, and a third writes tests or verifies the UI in the browser. You can record how the stages relate with worktree relationships such as Reviews, Validates, and Depends On, which show up as badges on the board. Custom Actions turn a reusable prompt, such as your review checklist, into a step you can send to the worktree's agent.
Manager–worker: the orchestrator agent#
An orchestrator agent plans and delegates instead of editing code. Anthropic's guide to building effective agents calls this the orchestrator-workers workflow, and recommends it for coding work where you can't know in advance which files a change will need to touch.
Agentastic's Manager Agents apply that pattern over days or weeks. You write a charter, such as keeping CI green or shepherding open pull requests. The manager wakes on a heartbeat between 15 minutes and daily, and also when a worker finishes or fails, a watched Sentry query returns new issues, or someone sends it mail. Workers are full worktree agents it starts with dev agent create. Objectives can carry a verification, such as a shell command whose exit code decides whether the objective is met, and text from issues or mail reaches the manager marked as untrusted. One caution: managers have no built-in token budget, so pacing comes from the heartbeat and the events you connect.
Scheduled maintenance#
A scheduled agent freezes a complete launch, including repository, agent, prompt, plugins, and environment, and runs it once, on an interval, daily, weekly, monthly, or on a cron expression. Presets cover finding critical bugs, adding test coverage, and generating docs. Memory documents carry what earlier runs learned.
Issue intake#
Work should start from where it already lives. Link a Linear or Sentry issue in Agent Home and its details are added to the prompt, and the issue stays attached to the worktree and its Kanban card. Mention the bot in Slack and the Mac starts a session, then posts the final answer back in the thread. Issues do not become pull requests by themselves: you, a schedule, or a Manager Agent starts each run.
Claude Code and Codex agent orchestration#
Start with what the providers ship. Claude Code's parallel work guide lists five options: subagents, agent view (a research preview), agent teams (experimental and disabled by default), dynamic workflows, and projects (a public beta on Pro and Max). Its docs note that agent teams don't isolate teammates in worktrees. Codex enables subagent workflows by default in current releases.
Add a control plane when you want Claude Code and Codex on the same backlog, one provider reviewing the other, containers or remote hosts, or one attention queue for everything. With Agentastic, a script can launch both:
# --label must name a label that already exists in the repository
dev agent create --repo ~/src/shop --agent claude \
--name fix-checkout-rounding --label "In progress" \
--prompt-file tasks/checkout-rounding.md
dev agent create --repo ~/src/shop --agent codex \
--name zero-coupon-tests --mode container \
--prompt "Add tests for zero-value coupons and run the suite."
dev --json agents | jq '.agents[] | {display_name, worktree_path, waiting_for_input}'Each command creates a worktree and branch, runs the setup script, and starts the agent. Follow-ups go through dev agent task --session <id> or dev send, and a Manager Agent can adopt agents you started yourself with dev manager link. Our guides to parallel Claude Code agents and driving agents from the dev CLI go further.
When you don't need orchestration#
Orchestration has costs, and sometimes they outweigh the gains.
- One task at a time. If the work is sequential, a single agent in one worktree is simpler and cheaper.
- Overlapping changes. Two agents refactoring the same module produce merge conflicts, not speed.
- Coding tasks that don't split. Writing about its multi-agent research system, Anthropic noted that most coding tasks have fewer truly parallel pieces than research, and that its multi-agent setup used about 15 times the tokens of a chat.
- Review is already full. If finished diffs wait for you, more agents lower throughput. Review is the real bottleneck of an AI software factory.
Start with one agent and one worktree, add a second on unrelated work, and automate intake last. How much to let agents do unreviewed is the subject of agentic engineering vs vibe coding.
Choosing a coding agent orchestration tool#
Check the eight primitives against your platform and providers. If your machine is a Mac and you use more than one coding agent, Agentastic covers all eight in one native app; it is free, closed source, and macOS only. For cross-platform teams, a terminal-first setup, or a single provider, the coding agent orchestration tools comparison explains where Paseo, Orca, Superset, Conductor, Nimbalyst, Claude Squad, and cmux fit. For the workspace side, see what an agentic IDE is, the multi-agent IDE, and the AI software factory.
Sources#
- Claude Code: run agents in parallel, agent teams, subagents
- Codex subagents, Codex worktrees
- Anthropic: Building effective agents, How we built our multi-agent research system
- LangGraph overview, CrewAI, OpenAI Agents SDK, Microsoft Agent Framework
- Agentastic docs: Manager Agents, system-wide dev CLI, scheduled agents, Kanban, multi-agent programming
- On this site: best agentic IDEs, what is an agentic IDE?, parallel coding agents workflow
Frequently asked questions#
What is AI agent orchestration?#
AI agent orchestration is coordinating several AI agents toward one goal: deciding which agent does what, where it runs, how its result is checked, and what happens next. In software development it means assigning tasks to coding agents like Claude Code and Codex, isolating each one, and reviewing their diffs before anything merges.
What is the difference between an agent orchestration framework and a coding agent orchestrator?#
Frameworks such as LangGraph and CrewAI are libraries for building agents into your own application, with state, retries, and tracing handled in code. A coding agent orchestrator runs existing coding agents against your repository, gives each task an isolated workspace, and routes the output to review and a pull request.
How do you orchestrate Claude Code agents?#
Inside Claude Code you can use subagents, agent view, agent teams, and Git worktrees. To run Claude Code next to other agents, in containers or on remote hosts, or under a long-running orchestrator agent, use a control plane such as Agentastic, which launches the claude CLI in its own worktree for each task.
What is an orchestrator agent?#
An orchestrator agent plans and delegates instead of editing code: it splits work into tasks, starts worker agents, checks their results, and decides what happens next. Agentastic's Manager Agents work this way, starting workers through the dev CLI and reporting to a live dashboard.
What are the most common agent orchestration patterns?#
For coding agents the common patterns are fan-out (one task to several agents, keep the best result), split (one feature into independent tasks), pipeline (implement, then review, then verify), manager-worker (an orchestrator agent delegates), scheduled maintenance, and intake from issue trackers or chat.
What are the best coding agent orchestration tools?#
Agentastic is the native Mac control plane for a broad mix of agents, Paseo and Orca lead for cross-platform and mobile control, Conductor offers a focused Mac worktree flow, and Claude Code and Codex have capable built-in options for a single provider. Our orchestration tools comparison covers each one.
When do you not need agent orchestration?#
Skip it when you work on one task at a time, when tasks touch the same files, or when agents already produce diffs faster than you can review them. Coordination costs tokens and attention, so add a second agent only after a single agent's loop is reliable.
Put your coding agents on one control plane
Agentastic is free on macOS and runs Claude Code, Codex, Gemini, and dozens of other agents in isolated worktrees, with Manager Agents and a scriptable dev CLI.
Try Agentastic on macOS