How to Orchestrate Multiple AI Agents with Orca

You can run five Claude Code agents in five worktrees. Congratulate yourself, you have solved isolation. Now answer the real question: who coordinates them?

By default, you do. You do it by tabbing between panes, reading half-finished output, and copy-pasting one agent’s findings into another agent’s prompt. That is not orchestration. That is being a very expensive message bus.

Orca’s orchestration skill replaces you with a coordinator agent. Here is what that actually looks like.

The Version You Care About

You describe a job. One agent breaks it into tasks, spawns a worker for each one in its own worktree, and then blocks, waiting for them.

You close the laptop.

Twenty minutes later your phone buzzes: worker eu-promos is asking whether it should change a shared component or just the page. You read the scrollback, tap shared, and put the phone back in your pocket. It buzzes twice more with worker_done notifications. You never opened a terminal.

That is the whole pitch. Everything below is how it works.

Why Parallel Agents Fall Apart Without It

Single agent, one terminal, one goal. It works. Two agents on different files: fine, if you split the work by hand. Five agents with one “fan out and fix everything” prompt? That is when it collapses.

Agents don’t coordinate with each other. They don’t share context, they don’t tell their peers what they changed, and they definitely don’t ask permission before touching a shared file.

Orca fixes this in two layers:

Worktrees give each agent its own directory, branch, and file state. No more “who is editing package.json?”
Orchestration adds a coordinator on top: tasks, workers, and a message inbox, so one agent runs the fleet.

This article is about the second layer, the least documented part of Orca. If worktrees are new to you, I covered why they’re the safety net for parallel agents previously.

Orca in Three Lines

Orca is a desktop app, MIT licensed, Y Combinator backed, around 51k stars on GitHub. macOS, Windows, Linux.

It calls itself an “Agent Development Environment” instead of an IDE. An IDE is built for you. An ADE is built for you and your agents.

The unit is the worktree: every task gets its own git worktree, its own terminal, its own browser tab. Agents run inside it on your existing subscriptions. Claude Code, Codex, Cursor CLI, OpenCode, Gemini, Copilot, or any other CLI agent.

Three Concepts, Not Fifteen

The docs list a handful of primitives. You only need to hold three in your head:

Concept	What it is
Run	The namespace for a project of work, and the coordinator’s inbox. Every message lands here.
Task	A work item with a spec, dependencies, and a status. It outlives any single attempt.
Worker	One agent, in one worktree, working one task. It must report back when it finishes.

There is a fourth thing worth knowing about, but not memorizing: every worker launch creates a dispatch, and completion messages must carry both the task ID and the dispatch ID. That is the rule that stops a stale, abandoned worker from marking newer work as done. Your coordinator handles the plumbing. You just benefit from it.

What You Say vs. What Runs

This is the part that makes orchestration click. You are not typing these commands. Your coordinator agent is.

You say:

Split checkout v2 three ways. Fix ZIP validation, apply EU promo codes at the cart level, and refresh the e2e snapshots. Ask me before touching anything shared.

Your coordinator runs:

# The durable namespace every message lands in
orca orchestration run-create \
  --objective "Ship checkout v2: validation, promos, regression pass" \
  --json

# One task per independent piece of work
orca orchestration task-create --spec "Add US ZIP+4 and Canadian postal validation" --json
orca orchestration task-create --spec "Apply EU promo codes at the cart level" --json
orca orchestration task-create --spec "Refresh checkout e2e snapshots" --json

# Fan a worker out to each one, before waiting on any of them
orca orchestration worker-start --task <val_id>   --worktree new-child --name us-val      --agent claude   --json
orca orchestration worker-start --task <promo_id> --worktree new-child --name eu-promos   --agent codex    --json
orca orchestration worker-start --task <e2e_id>   --worktree new-child --name e2e-refresh --agent opencode --setup run --json

Three workers, three isolated branches, three fresh terminals. All placed before anything blocks.

Then the coordinator does the one thing that makes this a loop instead of a fire-and-forget:

orca orchestration check \
  --wait \
  --types worker_done,escalation,question \
  --timeout-ms 900000 \
  --json

No sleep loops. No polling. The wait returns the moment something needs a human, and not a second before.

💡 A wait timeout is not a failure. Long coding tasks routinely run 15 to 60 minutes. The CLI emits heartbeat lines to stderr every 15 seconds while waiting; stdout is the actual result.

When a worker finishes, it sends exactly one worker_done, with an outcome, a short summary, and the files it touched. The coordinator reads the output, releases the terminal, and lets dependent tasks unblock:

orca orchestration worker-read    --dispatch <dispatch_id> --limit 80 --json
orca orchestration worker-release --dispatch <dispatch_id> --json

That is the entire model:

Run → Task → Worker → worker_done → next task

The One Distinction Worth Learning: Ask vs. Gate

Both pause work until someone decides. They pause different things, and picking wrong is the most common mistake.

ask is a worker asking upward. It blocks that one worker, mid-task, until the coordinator replies:

orca orchestration ask \
  --question "Should I update the shared component or only this page?" \
  --options "shared,page-only" \
  --timeout-ms 600000 \
  --json

The coordinator (or you, from your phone) answers, and the worker carries on.

A gate is the coordinator holding a task hostage. Nothing runs until a decision is recorded:

orca orchestration gate-create \
  --task <promo_id> \
  --question "Merge promo codes into the main branch now?" \
  --options '["yes","wait"]' \
  --json

Rule of thumb: use ask for “I need one answer to keep going”. Use a gate for “nobody proceeds until this is settled”. Resolving a gate cascades to every dependent task automatically.

Orchestrate From Your Phone

The point of a coordinator is that you are not chained to the terminal. Orca ships a mobile companion (iOS and Android, still in beta) that pairs with your desktop.

Orchestration is what makes mobile useful. The desktop keeps running the coordinator loop and the workers. The phone is the read-mostly surface you actually want when you are away from the desk: who is working, what they did, and who needs an answer.

Pairing takes a minute:

Install the app: App Store, TestFlight, or Android APK.
On desktop, open the pairing flow from the account menu. Orca shows a one-time code.
On mobile, choose Pair and paste it. Prefer Orca Relay when available, since it doesn’t depend on being on the same network.

From the phone you can see every worktree and its status across every connected host, read terminal scrollback, reply to a waiting agent by voice or text, review and commit source control changes, run saved Quick Commands, and get a push notification the moment an agent finishes.

⚠️ If pairing fails: both sides must be signed into the same Orca account, and codes expire after a few minutes. Tap Retry before you Re-pair. Mobile and desktop speak a versioned protocol, so keep both current.

The desktop is always the source of truth. The phone is a steering wheel, not an engine. Answering a question in the app and running orca orchestration reply on the desktop do exactly the same thing.

What You Stop Doing

Concretely, once the coordinator owns the loop:

No copy-pasting terminal output between panes to keep agents in sync.
No sleep 300 and checking whether it finished.
No wondering which of five agents touched package.json.
No sitting at the desk because an agent might ask something in twenty minutes.
No finished worker terminals left open just so you can re-read the output. Release them; the scrollback is archived.

When to Reach for It

Orchestration is not always the right tool. The boundary is clean:

orca terminal send for a one-off prompt in a terminal that already exists.
worker-start when the worker must report back, ask questions through the coordinator, and be tracked by task ID.
Run + tasks + workers when you want a durable namespace and a supervised multi-agent loop.
Worktrees directly for a full one-time handoff with no supervision. That is the worktree handoff flow, not orchestration.

Reach for orchestration when you need ownership, completion tracking, or a dependency graph. For everyday worktree management and terminal control, the plain Orca CLI is enough.

Takeaway

Worktrees solved the first half of the problem: every agent in a safe, real git branch. Orchestration solves the second half: something that dispatches the work, knows when it is done, and interrupts you only when a human actually has to decide.

Start small. One Run, one Task, one Worker. Watch the coordinator preamble get injected, then watch the worker report back. Do it once and you will never hand-roll an agent fleet from a shared terminal again.

Two things before you automate anything. Enable orchestration under Settings → Experimental, and confirm the runtime is up with orca status --json. Then get the version-matched guide straight from the binary:

orca skills get orchestration --full

Command names change between releases. That guide is the source of truth, not this article.

Useful links: