Skip to main content
Run multiple Codex agents by asking one chat to delegate bounded tasks to subagents, or by starting independent chats for separate pieces of work. Use separate Git worktrees when independent chats will edit the repository. Give each task an owner, then review and test the combined result. You can do this with Codex’s native tools. AMS is optional: it gives independent tasks a shared conversation when decisions or findings need to cross chat or tool boundaries.

Does Codex have subagents?

Yes. Codex subagents are delegated agents that a parent Codex chat starts for a specific task. The parent coordinates their work and combines their findings into one response. Current releases enable subagent workflows by default. Ask for delegation directly, or use applicable AGENTS.md or skill instructions that request it. Native delegation works without AMS. See the official OpenAI subagent documentation. Inspect the delegated threads from subagent activity in the app, or use /subagents in an interactive CLI session. Ask the parent to steer or stop a running subagent when its scope needs to change.

Prerequisites

  • A working, signed-in Codex app or CLI with access to the repository.
  • Your repository’s instructions, including AGENTS.md, and its normal validation commands.
  • Git for worktrees. The small example below uses a POSIX shell and Node.js 22 or newer, with no third-party packages.
  • For the optional AMS exercise, an authenticated AMS CLI and two independent tasks in the same workspace.
Product details checked against official OpenAI documentation on 5 November 2026. The prompts below are examples to adapt, not transcripts of a production change.

Choose a Codex multi-agent workflow

Prefer a single chat when each step depends on the previous result, or when the task is too small to justify coordination. Use parallel work when you can give each agent a clear question, allowed paths and a result that can be checked independently. A worktree is a Git checkout, not an agent or a parent-child relationship. A new independent chat is a separate conversation. Reading the same repository does not give it another chat’s private transcript. OpenAI describes these boundaries in Projects and chats. Provide the goal, contract, relevant paths and expected evidence explicitly. See sharing context between coding agents for longer handoffs.

Try a small delegated task

This exercise divides a label-normalization function and its tests between two subagents. The behavior is specified up front, so neither has to wait for the other to design the interface. The example is deliberately small. A single agent would usually finish this function faster; its purpose is to make ownership and verification easy to inspect before applying the pattern to larger work.

1. Create a disposable project

Run these commands in a directory where codex-parallel-demo does not already exist:
Open this directory as a project in the Codex app, or start an interactive CLI chat from it:
Choose permissions that allow edits and local Node commands in this project. Keep the repository’s existing approval rules for a real codebase.

2. Give each subagent one file

Send this to the parent chat:
Confirm that two delegated threads actually appear, with one implementation owner and one test owner. A written plan to delegate is not evidence that subagents ran. The expected result is one implementation file and one test file. Starting two ordinary chats yourself would create independent tasks instead; it would not make one the other’s parent.
A subagent is not automatically a separate Git worktree. Plan for shared files unless you have explicitly arranged separate checkouts. File ownership in a prompt is a coordination rule; it is not a filesystem permission boundary.

3. Review and verify the combined result

After both agents finish, the parent should inspect the actual files. A plausible implementation is:
Check that the tests assert the contract, rather than merely repeating the implementation. For example, include input such as " Hello World ", "Hello World\tAgain\nToday", and "Hello, World!". The expected results are "hello-world", "hello-world-again-today", and "hello,-world!". Run the verification yourself from the project directory:
The completion condition is exit status 0, four passing tests, no failures, and changes confined to the two assigned files. A parent summary that says “done” without the files and test result is not enough. For a second review pass, ask:

Run independent Codex chats in worktrees

Use independent chats for changes with separate lifetimes: for example, an API fix and a documentation update that you want to review separately. A branch name alone does not isolate files inside one checkout. In the app, start a new chat in Worktree mode and choose its starting branch. Repeat for the second task. Confirm that each chat reports a different working directory before allowing parallel edits. App-created worktrees normally start with a detached HEAD; create a task branch when your repository’s workflow requires one. See OpenAI’s worktree guide. For CLI sessions, first prepare separate worktrees using your project’s approved workflow. Open one terminal in each assigned checkout:
In current CLI clients connected to a shared local or remote server, /agents opens the chat command center. /subagents selects a delegated thread within the current session. See OpenAI’s developer commands. Before editing, have each task run:
Agree on the base revision, file ownership and integration owner. Each task should return its changed paths, validation results and unresolved decisions. The integration owner reviews both changes and runs the relevant checks again after combining them through the repository’s normal Git workflow. Passing tests in two separate checkouts do not prove that the combined change passes. Read-only investigations can often share a checkout. Keep it stable while reviewing: another task’s edits can change the evidence underneath the reviewer. For detailed checkout creation, resource isolation and integration commands, use Git worktrees for AI coding agents.

Add an optional shared AMS conversation

Native delegation already returns findings to its parent. Use AMS when independent tasks need a place to discuss an interface, record ownership or hand work to a task in another coding tool. For an implementation and review involving Claude Code, use the Claude Code and Codex guide.

Connect the two tasks

Complete the quickstart and deliberately enable the repository or worktrees you want to coordinate, following folder and repository workspace setup. An installed integration or inherited profile does not activate an unconfigured folder. In each agent’s own shell, start with the offline activation check:
Continue only when the command succeeds and reports enabled: true. If it reports false, automatic coordination stays off until you explicitly enable the intended workspace and scope. If the check fails or is unsupported, resolve that error or update the CLI through your approved path; do not fall back to another profile or unguarded commands. In an enabled folder, guard the coordination commands:
Confirm the same workspace and different agent instances. Let Codex supply its host task identity; do not copy one chat’s identity into another. If worktrees select different destinations, follow folder and repository workspace setup before proceeding. Have one task create a channel, or agree on an existing channel from ams --require-workspace channels:
Then run in both tasks:
Creating a channel does not select it. Repeat the resumed read while its footer says (more available). Each task keeps its own progress. If the installed CLI does not recognize --resume, update through your approved CLI update path.

Verify a useful handoff

Give task A a specific request to send:
Continue task B in its Codex chat and have it run ams --require-workspace messages --resume, inspect the relevant code, and reply with its finding or acknowledgement. Return to task A and have it read again. An effective response identifies the path, the behavior and the next action; a bare “received” does not resolve an interface question. This is an illustrative handoff. In a real project, include the worktree or revision and actual test evidence. Wait for acknowledgement before a change that depends on the other owner accepting a new contract.
AMS stores shared messages. It does not automatically copy private session history or wake and resume every agent. A successful send proves storage, not that the recipient read or accepted it. Continue an inactive task through its host, then have it read the channel.
For foreground updates, ams --require-workspace message watch --resume follows messages while its process stays alive and the host surfaces its output. Read again when a task resumes and before it finishes. For reusable coordination instructions or an MCP alternative, see Connect Codex to AMS.

Keep the boundaries explicit

  • Shared files: give shared manifests, lockfiles, migrations and generated files one owner. Worktrees prevent immediate overwrites, but overlapping changes can still conflict during integration. They share Git refs: do not move or delete another task’s branch.
  • Permissions: subagents inherit parent sandbox and approval settings. “Review only” is an instruction, not a separate enforced sandbox. Independent chats need their own appropriate permission settings.
  • Context: put durable project rules in AGENTS.md; give each task the decisions and evidence it needs. A shared directory or AMS membership does not make all conversation history available.
  • Test resources: separate checkouts can still use the same port, database, external account or fixture. Assign isolated resources or serialize those tests. Keep the detailed setup in the worktree guide.
  • Capacity: parallel agents consume additional model usage and can compete for CPU, memory and service limits. Start with a few independent tasks; more agents do not guarantee faster completion.

Troubleshoot parallel work