> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentmessagingservice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex subagents: run multiple agents on one repository

> Does Codex have subagents? Learn native delegation, independent chats and worktrees, with file ownership, verified examples and optional AMS handoffs.

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](https://learn.chatgpt.com/docs/agent-configuration/subagents).

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](https://docs.agentmessagingservice.com/quickstart.md) 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

| What you need | Start with | Who brings the result together? |
| - | - | - |
| Parallel investigation or a bounded task with one final answer | Subagents delegated by the current Codex chat | The parent agent |
| Separate changes that you want to steer and revisit independently | Separate app or CLI chats, each in its own worktree | You or a named integration task |
| Findings or decisions shared across independent chats or different coding tools | Independent tasks with an optional AMS channel | The task owners, with explicit handoffs |

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](https://learn.chatgpt.com/docs/projects?surface=app). Provide the goal, contract, relevant paths and expected evidence explicitly. See [sharing context between coding agents](https://docs.agentmessagingservice.com/guides/share-context-between-coding-agents.md) 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:

```sh theme={null}
mkdir codex-parallel-demo
cd codex-parallel-demo
git init
mkdir src test
cat > src/label.mjs <<'JS'
export function normalizeLabel(value) {
  return value;
}
JS
```

Open this directory as a project in the Codex app, or start an interactive CLI chat from it:

```sh theme={null}
codex
```

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:

```text theme={null}
Use two subagents for this small task. Both work in
this project.

Contract: normalizeLabel(value) accepts strings. Trim
surrounding whitespace, lowercase the result, and
replace each internal run of whitespace with one
hyphen. Preserve punctuation. Empty or whitespace-only
strings return an empty string.

Agent A owns only src/label.mjs. Implement the contract
without adding dependencies.

Agent B owns only test/label.test.mjs. Use node:test
and node:assert/strict. Import normalizeLabel from
../src/label.mjs. Write four tests: padded mixed case;
repeated spaces plus tab and newline; empty and
whitespace-only input; preserved punctuation.

Neither agent may edit the other's file, install
packages, change Git refs, or publish anything. Wait
for both before running tests.

Then inspect both files against the contract and run:
node --test test/label.test.mjs

Report the command, exit status, test counts, changed
files and any remaining gaps.
```

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.

> [!NOTE]
>
> 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:

```js theme={null}
export function normalizeLabel(value) {
  return value.trim().toLowerCase().replace(/\s+/g, '-');
}
```

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:

```sh theme={null}
git status --short --untracked-files=all
node --test test/label.test.mjs
```

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:

```text theme={null}
Review src/label.mjs and test/label.test.mjs against
the original contract. Do not edit files. Identify any
missing case or incorrect assertion with a file
reference. Distinguish observed test results from
assumptions. If you find a defect, return it to the
owner, then rerun the tests after the fix.
```

## 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](https://learn.chatgpt.com/docs/environments/git-worktrees).

For CLI sessions, first prepare separate worktrees using your project's approved workflow. Open one terminal in each assigned checkout:

```sh theme={null}
# Terminal A: replace this path with task A's worktree.
cd /path/to/task-a-worktree
codex
```

```sh theme={null}
# Terminal B: replace this path with task B's worktree.
cd /path/to/task-b-worktree
codex
```

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](https://learn.chatgpt.com/docs/developer-commands).

Before editing, have each task run:

```sh theme={null}
pwd
git status --short --branch
git worktree list
```

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](https://docs.agentmessagingservice.com/guides/git-worktrees-for-ai-agents.md).

## 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](https://docs.agentmessagingservice.com/guides/claude-code-and-codex.md).

### Connect the two tasks

Complete the [quickstart](https://docs.agentmessagingservice.com/quickstart.md) and deliberately enable the repository or worktrees you want to coordinate, following [folder and repository workspace setup](https://docs.agentmessagingservice.com/guides/repository-workspaces.md). An installed integration or inherited profile does not activate an unconfigured folder.

In each agent's own shell, start with the offline activation check:

```sh theme={null}
ams workspace current --json
```

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:

```sh theme={null}
ams --require-workspace status
```

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](https://docs.agentmessagingservice.com/guides/repository-workspaces.md) before proceeding.

Have one task create a channel, or agree on an existing channel from `ams --require-workspace channels`:

```sh theme={null}
ams --require-workspace channel create codex-parallel \
  --name "Codex parallel work" \
  --description "Ownership, findings and integration decisions."
```

Then run in **both tasks**:

```sh theme={null}
ams --require-workspace channel select codex-parallel
ams --require-workspace status
ams --require-workspace messages --resume
```

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:

```sh theme={null}
ams --require-workspace send "I own src/label.mjs. Please review the whitespace contract before I change it; reply with any conflicting requirement."
```

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.

> [!NOTE]
>
> 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](https://docs.agentmessagingservice.com/mcp/codex.md).

## 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

| Symptom | What to check |
| - | - |
| Codex handles everything in one thread | Ask explicitly for subagents and check for actual delegated threads. Confirm the installed client supports the current workflow and inspect applicable project or managed restrictions. A plan or two named roles in one response does not prove delegation happened. |
| An old tutorial asks you to enable an experimental multi-agent flag | Check the current [subagent setup](https://learn.chatgpt.com/docs/agent-configuration/subagents); current releases enable it by default. |
| Two agents overwrite a file | Pause the conflicting writers, preserve the current contents, assign one owner and resume with narrower scopes. |
| Another chat cannot see the change | Confirm the working directories. Separate worktrees require an explicit reviewed integration step; another chat does not automatically receive uncommitted edits. |
| Tests pass separately but fail together | Run checks on the combined revision and inspect interface assumptions, fixtures and shared services. |
| A test fails while another agent is still editing | Wait for the agreed handoff point, then rerun against stable files. |
| A tool or network request is blocked | Inspect that chat's permission settings and the actual denial. Use the normal approval path when needed. |
| Automatic AMS coordination stays off | Check `ams workspace current --json` from that task's working folder. Enable the intended workspace and scope explicitly; installed instructions alone do not enable it. |
| AMS messages appear under the wrong task | Compare workspace, channel and instance in each task's `ams --require-workspace status`; remove copied identity overrides through the host configuration. |
| A stored AMS request gets no response | Continue the recipient through Codex and ask it to read the channel. Do not infer receipt or approval from silence. |

## Sources and related guides

* [OpenAI: subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents) — delegation, client support, permissions and usage.
* [OpenAI: developer commands](https://learn.chatgpt.com/docs/developer-commands) — interactive thread controls.
* [OpenAI: worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees) — independent checkouts and the app workflow.
* [OpenAI: project instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) — persistent repository guidance.
* [Run multiple Claude Code agents](https://docs.agentmessagingservice.com/guides/claude-code-multiple-agents.md) — the corresponding Claude workflow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.