Codex orchestrator: how to run multiple Codex agents at once

A Codex orchestrator is the layer that runs several Codex agents at once without them colliding. It splits a goal into independent tasks, gives each agent its own branch and working copy, tracks who owns what, collects diffs and test results, routes decisions to you, and keeps runs alive after you close the laptop.

Can you run multiple Codex agents at the same time?

Yes, and there are three common ways to do it.

• Several CLI sessions. Open the Codex CLI in separate terminals, each pointed at its own copy of the repo.
• Scripted runs. codex exec runs a task without the interactive interface and prints the final message to stdout. Add --json and you get a stream of machine-readable events your own code can watch.
• Cloud tasks. Send tasks to Codex cloud, where each task gets its own workspace and comes back as a diff you can review, follow up on, or open as a pull request.

The Codex app also has built-in worktree support, so parallel threads can work on one repo without conflicts.

Starting agents is the easy part. What limits you is everything around them. Every agent draws on the same plan's usage limits, every agent's output lands in your review queue, and every agent that stops to ask a question waits until you notice. Running five agents is a coordination problem long before it is a compute problem.

How do I stop parallel Codex agents from overwriting each other?

Give every agent its own working copy and its own branch. Git worktrees are the cheapest way to do that locally, because every worktree shares one repository but has its own checkout:

git worktree add -b agent/billing ../app-billing
git worktree add -b agent/search ../app-search
cd ../app-billing && codex exec --sandbox workspace-write \
  -o ../results/billing.md "Add proration to plan upgrades. Run npm test before you finish."

Then add three rules that prevent most of the pain:

1. One owner per file area. If two tasks touch the same migration, schema or config file, run them in sequence.
2. Shared instructions in AGENTS.md. Codex reads it, so conventions, test commands and paths agents must never touch live in one place every agent sees.
3. Separate runtime resources. Use different dev server ports, separate test databases and separate seed data. Two agents running integration tests against one database produce failures that belong to neither of them.

Merge one branch at a time and rebase the others onto main after each merge, so conflicts surface while the work is still fresh.

Should Codex agents run locally or in the cloud?

Both work. They suit different kinds of tasks.

Local wins when you need your exact environment and want to steer while the agent works. Cloud wins when tasks are independent and you would rather review than babysit. You can also mix them: local for the task you are pairing on, cloud for the queue.

Either way, something still has to track which task is where, which ones wait on you, and where the results land.

What does a Codex orchestrator actually have to do?

Starting processes takes a shell loop. An orchestrator earns the name by doing five jobs reliably:

• Split the work. Turn one goal ("ship usage-based billing") into tasks that can run independently, each with a clear definition of done and a test command.
• Track owners. Record which agent owns which task, branch and file area, so two agents never get the same job and you can answer "who has the webhook handler?" at a glance.
• Collect results. Gather each run's diff, test output, final message and any preview link into one place tied to its task, so nothing stays buried in a terminal.
• Ask for approvals. When an agent needs a decision, a sign-in or a sign-off on a deploy, put the question in one queue you actually check, and park the run until you answer.
• Keep runs alive. Survive closed laptops, dropped connections and usage limits, then resume where the run stopped.

A setup that handles the first three but not the last two works while you watch and stalls the moment you leave. For how these jobs chain into a repeatable flow, see agent orchestration pipeline.

How should I split work across Codex agents?

Split along seams the codebase already has: a module, an endpoint, a test suite, a page, or a package in a monorepo. Avoid seams that cut through shared state, such as two agents on the same database migration, or one agent changing an API while another consumes it.

A pattern that holds up:

1. Contract first. One agent writes the interface (types, API schema, function signatures), and you merge it before anything else starts.
2. Fan out. Each remaining task goes to its own agent, all building against the merged contract.
3. One reviewable pull request per task. If you could not review the diff in one sitting, split the task again.
4. Write the finish line into the prompt. "Done when npm test passes and the new endpoint returns 200 for the fixtures in tests/billing" gives the agent a target. "Add billing" gives it a guess.
5. Integration last. One final task merges the branches, runs the full suite and fixes whatever broke at the seams.

Good splits also make review faster, because every diff answers one question.

Why do multi-agent Codex setups stall?

From the outside, most stalls look the same: you come back and nothing moved. The usual causes:

• A question in a closed tab. The agent asked for permission or a choice, and the terminal holding that prompt is gone.
• A usage limit mid-run. Several agents on one plan hit the limit together, and every run stops at once.
• A sleeping machine. Local runs end when the laptop lid closes.
• Lost context. A week later nobody remembers which branch held which experiment, so finished work never merges.
• Review backlog. Agents finish faster than you review, and the queue becomes the bottleneck.

The fixes are boring, and they work. Run agents somewhere that stays on. Write every task's state somewhere durable. Send every question to one place. Schedule recurring work (dependency bumps, flaky test sweeps, changelog drafts) so it shows up as planned tasks, and stops depending on you remembering to open a session. If you run Claude Code too, the same ideas apply in Claude Code orchestration.

How does Kavela run Codex workers?

Kavela is a cloud workspace where one agent, Kav, does the orchestrator's job: you give it the goal, and Kav plans it, files the tasks and hands each part to a worker.

• Your Codex plan. Set any worker to "My Codex plan" and Codex runs inside that worker's cloud computer on your subscription. You sign in once from a card.
• Its own computer. Each worker gets a container with a real shell, files, git and a browser, and Codex still reaches the workspace's skills and connected apps. Runs survive a closed tab or laptop.
• Limits handled. Connect more than one account and Kavela rotates across them as each hits its usage limit. When all are at their limit, the run pauses and asks you once: wait and resume automatically, finish on Kavela credits, or cancel.
• One Approvals inbox. Sign-ins, choices and deploys wait in one place (Telegram too). Everything else runs.
• A calendar. Tasks, routines (every Monday at 8:00, say) and webhook-triggered events land on a month, week or day view, with deliverables attached.

Kavela is in early access.

Already paying for Codex? Bring your plan and give Kav the first goal. Start your free trial