How to Run Multiple Codex Agents in Parallel

You can run multiple Codex agents in parallel in several genuinely different ways. The right one depends on whether you want independent coding tasks, delegated subagents inside one larger task, or remote jobs that keep working away from your machine.

The practical answer is:

Use Codex worktrees in the ChatGPT desktop app when you want first-party worktree management on macOS or Windows.
Use Codex CLI in manually created git worktrees when you want a terminal workflow or work on Linux.
Use Parallel Code when you want managed worktrees, a visual dashboard, and the option to run Codex beside other coding agents.
Use Codex subagents when one main task needs parallel research, review, or other bounded supporting work.
Use Codex cloud tasks when the work should run in hosted environments rather than on your computer.

For independent local tasks that can change code, give every task its own working directory and Git index—usually with a worktree. Create a branch when you decide to retain or integrate a result; managed tools may safely begin in a detached HEAD state. Running several write-capable Codex sessions in one checkout is not isolation.

Disclosure: Parallel Code is our product. This guide also covers OpenAI’s native options and the manual CLI workflow so you can choose the setup that actually fits.

The five ways to run Codex in parallel

Four options below provide an execution environment for independent tasks. Subagents are a delegation layer inside one parent task, so they can also be combined with any environment that supports them.

Approach	Best for	Isolation boundary	Main tradeoff
ChatGPT desktop worktrees	Several local Codex tasks with a first-party GUI	Managed worktree per Worktree-mode task	Codex-only and desktop-platform dependent
Manual CLI worktrees	Terminal users who want full control	Git worktree; create and manage the branch yourself	More setup and cleanup
Parallel Code	Visual local orchestration, Linux, or mixed agents	Managed branch and worktree by default; selected ignored paths may be shared	Another local app in the workflow
Codex subagents	Parallel exploration, review, tests, and triage within one task	Separate agent threads; do not assume separate branches or enforced read-only access	Write-heavy agents can still collide
Codex cloud	Remote, asynchronous tasks	OpenAI-managed cloud environment	Hosted setup and access requirements differ from local work

These approaches are complementary. You can run two independent feature tasks in worktrees while each task delegates read-only analysis to subagents. What matters is knowing which layer is providing the isolation.

Option 1: Use managed worktrees in the ChatGPT desktop app

OpenAI’s managed Worktree mode is the shortest path if you already use Codex in the ChatGPT desktop app. According to the official Codex worktree documentation, the app can create a separate git worktree for a task, start it from a branch you choose, and later move the task between the worktree and your local checkout with Handoff.

The basic workflow is:

Open a repository in the ChatGPT desktop app and select Codex.
Choose Worktree below the new-task composer.
Select the branch that should provide the task’s baseline.
Submit one focused task.
Repeat for every independent task you want to run.
Review each result in its worktree, create a branch there, or hand it off to Local for further testing.

Codex-managed worktrees start in a detached HEAD state by default. This avoids creating a pile of speculative branches before you know which results are worth keeping. If a result is good, you can create a branch in that worktree and continue toward a commit or pull request.

The app also supports setup scripts for preparing each worktree. If a task needs ignored local files, its .worktreeinclude mechanism can copy selected paths such as .env.local into managed worktrees. Be conservative with that list: every copied secret becomes available in another task environment.

When the ChatGPT desktop app is the best choice

Choose it when:

You use only Codex and want the tightest first-party workflow
You want the app to create, track, restore, and clean up temporary worktrees
You regularly move tasks between background worktrees and your foreground checkout
You develop on macOS or Windows

The managed Worktree feature is currently specific to Codex in the ChatGPT desktop app. The CLI does not need that feature to use worktrees, though—you can create them with Git and launch Codex inside each one.

Option 2: Run Codex CLI in manual git worktrees

The manual approach is portable, transparent, and built entirely from Git plus the Codex CLI. It is also the easiest way to understand what an orchestrator is doing for you.

Start from a known repository state. Check the current branch, record the base commit, and inspect existing worktrees before choosing new branch names and paths:

git status --short --branch
git rev-parse HEAD
git worktree list

Then create one worktree and branch per task. The following examples start both tasks from the current committed HEAD; replace HEAD with main or another explicit base when that is clearer. Choose branch names that do not already exist and target paths that are not already registered as worktrees.

git worktree add -b agent/api-validation ../my-repo-api-validation HEAD
git worktree add -b agent/integration-tests ../my-repo-integration-tests HEAD

Open a separate terminal in each directory and start Codex with a bounded prompt:

cd ../my-repo-api-validation
codex "Add request validation to the user API. Keep response shapes unchanged. Run the API tests and summarize the diff."

cd ../my-repo-integration-tests
codex "Add integration tests for the existing user API behavior. Do not change production code. Run the new tests."

The two Codex sessions now have separate working directories, indexes, and branches. A half-finished edit in one worktree does not appear in the other. Both worktrees still share the repository’s object database and refs, and their branches can conflict when you integrate them later.

Review and integrate one result at a time

When an agent finishes:

Read its summary, but treat the diff and test output as the evidence.
Inspect unstaged, staged, and committed changes with git status, git diff, git diff --cached, and git diff <base-sha>...HEAD.
Run the relevant checks yourself when the risk justifies it.
Commit the task branch if the agent has not done so.
Merge it or open a pull request according to your normal Git workflow.
Before updating another branch, pause its agent and commit or stash its work; then merge or rebase the new baseline before resuming.
Stop any servers or containers started from a finished worktree, then remove the clean worktree with git worktree remove <path>.
Delete its branch only after the result has been merged or deliberately discarded.

Our broader guide to using multiple AI coding agents on one repo covers task assignment and integration in more detail. The underlying git worktree isolation model is the same whether every task uses Codex or you mix several agents.

What manual worktrees do not isolate

A worktree isolates tracked files, ordinary untracked files, the working tree, and the Git index. Linked worktrees still share the repository’s object database, most refs and common Git metadata, repository-level configuration, hooks, and usually the same credentials. Worktree-specific configuration requires Git’s extensions.worktreeConfig and git config --worktree support.

Worktrees also do not automatically give every Codex session:

A different development-server port
A separate database
Independent Docker container names or volumes
Separate external service accounts
Independent API or subscription limits

If two tasks both start an application on port 3000, point migrations at the same database, modify a shared symlink target, or touch the same remote resource, they can still interfere. Filesystem isolation is necessary, but it is not complete environment or security isolation.

Option 3: Run Codex through Parallel Code

Manual worktrees work well, but every task adds branch naming, terminal management, progress tracking, diff review, and cleanup. Parallel Code automates that local workflow while still launching the installed Codex CLI.

The setup is:

Install and authenticate Codex CLI normally.
Install the latest Parallel Code release.
Open your repository in Parallel Code.
Create a task, select Codex, and submit the prompt.
Repeat for the other independent tasks.

By default, an isolated task gets its own branch and worktree. Direct mode and non-Git folders are exceptions. The dashboard keeps active Codex terminals and task states visible in one place, and the diff view lets you review the result before merging or discarding it.

There is an important shared-state setting to review before launch. Parallel Code detects ignored candidates such as .env and node_modules, preselects detected entries, and symlinks the selected paths from the main checkout into task worktrees. Deselect secrets, generated output, caches, or dependencies that must remain private or independently mutable. For stronger process isolation, Parallel Code also supports project-specific Dockerfiles.

Parallel Code is most useful when you want to:

Run Codex locally on macOS or Linux without manually managing worktrees
Keep using your preferred editor on each worktree
Run Codex beside Claude Code, Copilot CLI, Gemini CLI, or Antigravity CLI
Race several agents on the same task and compare their diffs
Monitor several long-running terminal sessions without juggling windows

If you only use Codex on macOS or Windows and prefer a first-party application, the ChatGPT desktop worktree flow may be the simpler choice. If you work on Linux, want an orchestrator that supports several major coding CLIs, or regularly compare different agents, Parallel Code covers a different workflow.

Option 4: Ask Codex to use subagents

Codex can also spawn specialized subagents inside a task. Current releases enable these workflows by default in the desktop app, CLI, and IDE extension. The main agent delegates bounded work, waits for the subagents, and combines their results. OpenAI’s subagent documentation recommends this pattern for parallel work such as exploration, tests, triage, and summarization.

If read-only access matters, first select a read-only permission mode for the parent turn or use custom agents configured with sandbox_mode = "read-only". Then make the behavioral intent explicit in the prompt:

Review this branch with three parallel subagents.
- One checks correctness and edge cases.
- One checks security boundaries.
- One checks test gaps.

Do not edit files. Wait for all three, then return one severity-ranked report with file references.

The prompt documents the intent; the sandbox enforces it. This is different from launching three independent feature tasks. Subagents are coordinated by one main task and return their findings to it. They are excellent for read-heavy work because noisy search results, logs, and intermediate reasoning stay out of the main thread.

Do not assume that every subagent has its own branch or worktree. OpenAI explicitly advises more caution with parallel write-heavy subagents because concurrent edits can create conflicts and coordination overhead. For several independent implementation tasks, explicit worktree isolation remains easier to reason about and review.

When subagents are the right form of parallelism

Use them when:

One task benefits from several independent investigations
You want specialized reviewers to examine the same diff
The outputs should be synthesized into one answer
Most delegated work is read-only or has clearly separated ownership

Use separate top-level worktrees when each result should produce its own independently reviewable branch.

Option 5: Dispatch parallel Codex cloud tasks

Codex cloud runs repository tasks in OpenAI-managed environments. This is useful when work should continue remotely, when you do not want several local builds consuming your machine, or when tasks need standardized hosted setup rather than your current checkout.

Before dispatching tasks:

Sign in with ChatGPT; API-key authentication supports local Codex workflows but not Codex cloud.
Confirm that your plan and workspace have cloud access, then connect the GitHub repository and select or configure its environment.
If you sign in with email and password, enable multi-factor authentication before using cloud tasks.
Choose the branch or commit SHA for each task, submit one bounded prompt per task, and review the returned answer and diff before opening a pull request or applying the result locally.

Cloud tasks have phase-specific configuration. Environment variables remain available during setup and the agent phase. Secrets are available only to setup scripts and are removed before the agent begins, so do not configure an agent-time credential as a secret. Setup runs with internet access; agent internet access is off by default and should be enabled only as narrowly as required. Common package managers can be configured automatically, while more complex repositories need explicit setup or maintenance scripts. See the cloud environment documentation and authentication requirements.

A task that works only because of an undocumented local dependency may behave differently in the cloud.

Choose cloud tasks for asynchronous, offloaded work. Choose local worktrees when exact access to your machine, local services, or interactive development environment matters.

How to choose the right approach

First decide whether you need independent code changes or supporting work inside one parent task. Independent changes need separate environments: choose the ChatGPT desktop app for first-party local management, manual worktrees for terminal control, Parallel Code for visual local orchestration or mixed CLIs, and cloud for offloaded hosted execution. Use subagents when the result should be synthesized back into one parent task.

For a first attempt, two independent worktrees are enough. Add concurrency only when the work splits cleanly and review is not already the bottleneck.

A safe parallel Codex workflow

The reliable principles are similar across worktree-based approaches, but the exact controls differ. Subagents inherit their parent permissions, while cloud tasks use hosted environment and network settings.

1. Start from one known baseline

Start every task from a baseline you can identify later. Manual worktrees can use an explicit commit; cloud accepts a branch or commit SHA; the desktop app starts from a selected branch’s HEAD and can deliberately carry that branch’s local changes. Do not assume uncommitted changes are shared unless the selected tool explicitly copies or applies them.

2. Give each task one observable outcome

“Improve the API” invites overlapping edits. “Reject invalid pagination values without changing valid responses” has a clear boundary and verification path. Our AI coding agent prompt template is designed for this kind of task brief.

3. Split by ownership, not just by intention

Two prompts can sound different while still changing the same controller, schema, and test file. Map the likely files and shared contracts before starting. The guide to splitting features into parallel agent tasks explains how to find safer seams.

4. Keep permissions proportionate

Every concurrent agent increases the number of commands and external actions that may happen at once. For local Codex clients, keep approval and sandbox controls enabled unless broader access is genuinely required. For cloud tasks, constrain environment variables, setup secrets, and agent internet access instead. Worktree isolation does not protect secrets or remote systems from an over-permissioned process.

5. Review before integrating

Run tests and inspect each diff independently. Merge one result, verify the combined baseline, then move to the next. The review burden grows with output volume even when execution time falls; use a consistent AI-generated code review checklist.

6. Watch aggregate usage

Each session or subagent performs its own model and tool work, including any repeated context and setup. Parallel execution concentrates that usage into a shorter period, but exact limits or charges depend on authentication, plan, model, retries, and task shape. Racing several Codex agents on one prompt deliberately adds redundant attempts. The cost guide for parallel agents explains that distinction.

Frequently asked questions

Can Codex run multiple agents at the same time?

Yes. You can run independent tasks in desktop worktrees, separate CLI worktrees, or cloud environments. Codex can also spawn parallel subagents within one task. These modes solve different problems, so “multiple agents” does not automatically mean “multiple isolated branches.”

Does Codex CLI create a worktree for every session?

Not by default. OpenAI’s managed Worktree mode is a feature of Codex in the ChatGPT desktop app. With Codex CLI, you can create worktrees using git worktree add, enter each directory, and start a separate Codex session there. External orchestrators can automate those steps around the CLI.

Do worktrees prevent merge conflicts?

No. They prevent concurrent sessions from modifying the same working copy. Overlapping textual edits may produce merge conflicts, but semantic or contract incompatibilities can merge cleanly and fail only in tests or at runtime. Worktrees make each result reviewable; they do not replace careful task boundaries and integration testing.

What is the best way to run multiple Codex agents on Linux?

Use Codex CLI in manual git worktrees if you prefer a terminal-only setup. Use Parallel Code if you want a native visual dashboard and automated worktree management. The managed Codex worktree interface is currently part of the macOS and Windows desktop app.

Should I use worktrees or subagents?

Use worktrees when each task should produce an independent code change that you can review, keep, or discard. Use subagents when one parent task needs parallel supporting work and one synthesized result. You can combine both patterns when the task boundaries are clear.

Start with two tasks

The fastest way to learn the workflow is not to launch ten Codex agents. Pick two small, independent tasks, start them from the same clean commit, and give each one an isolated worktree. Review and integrate both before increasing the concurrency.

Once that loop feels routine, choose the interface that removes the most friction from your environment while preserving explicit task boundaries, permissions, and review.