title: "Sub-Agents — Codex CLI" tested_with: codex-cli: "0.2.x" last_updated: 2026-03-21 status: proven difficulty: intermediate prerequisites: [03-prompting-for-agents]

Sub-Agents — Codex CLI

How Codex Handles Task Delegation

Codex CLI, OpenAI's open-source terminal coding agent, approaches sub-agents differently than Claude Code. Where Claude Code has a first-class Agent tool that the model invokes directly within a session, Codex CLI operates as a single-agent system by default. There is no built-in mechanism for the running Codex agent to spawn child agents within the same session.

This does not mean you cannot achieve sub-agent-like workflows with Codex. It means the patterns are different, and in some cases you orchestrate the delegation yourself rather than relying on the tool to handle it internally.

The Codex Sub-Agent Model

Codex CLI is designed around a single-agent loop: you give it a task, it works through that task step by step, and it returns the result. Its strength is in focused, sequential execution — reading files, reasoning about code, making edits, running commands to verify, and iterating.

Within this single-agent loop, Codex can decompose complex tasks into steps and execute them in order. It does this naturally, without sub-agents, by maintaining its plan in context and working through each step. For many tasks, this is sufficient and efficient. The overhead of sub-agent coordination is avoided entirely.

The key difference from Claude Code's model: in Claude Code, the parent agent can dispatch a sub-agent and continue thinking about the broader task while the sub-agent works on a specific piece. In Codex CLI, the agent handles everything sequentially within one context window. This means Codex is simpler to reason about but lacks the parallelism and context isolation that sub-agents provide.

Available Delegation Patterns

While Codex CLI does not have built-in sub-agents, several delegation patterns are available.

Sequential decomposition within a single session. Codex handles multi-step tasks by working through them one at a time. You can prompt for explicit decomposition:

Break this task into independent steps and execute them one at a time:
1. Add input validation to the /users endpoint
2. Add input validation to the /orders endpoint
3. Add input validation to the /products endpoint

Complete each step fully before moving to the next.

Codex will treat this as a sequential checklist, completing each item before moving on. You get the same work done, just not in parallel.

Scoped sessions. You can run multiple Codex sessions yourself, each focused on a different part of the task. Open three terminal windows, run codex in each, and give each one a specific, self-contained task. You are the orchestrator — you decompose the task, dispatch each session, and synthesize the results.

# Terminal 1
codex "Add input validation to POST /api/users following the pattern in src/validation/schemas.ts"

# Terminal 2
codex "Add input validation to POST /api/orders following the pattern in src/validation/schemas.ts"

# Terminal 3
codex "Add input validation to POST /api/products following the pattern in src/validation/schemas.ts"

This gives you parallelism, but you manage the coordination. If the sessions edit overlapping files, you will need to resolve conflicts manually.

Non-interactive mode for batch tasks. Codex CLI's non-interactive mode lets you script multiple invocations:

codex --quiet "Add unit tests for src/auth/login.ts"
codex --quiet "Add unit tests for src/auth/register.ts"
codex --quiet "Add unit tests for src/auth/reset-password.ts"

Each invocation is a separate session with its own context. You can run them sequentially in a script or in parallel using shell background processes. This is the closest analog to Claude Code's fan-out pattern.

Using the OpenAI Agents SDK for Orchestration

For teams that need true programmatic sub-agent orchestration, Codex CLI's underlying architecture integrates with the OpenAI Agents SDK. The Agents SDK is a Python framework for building multi-agent systems, and Codex CLI can serve as a tool within that framework.

The pattern looks like this:

Define a parent agent using the Agents SDK that understands the overall task.
Give the parent access to Codex as a tool — it can invoke Codex sessions programmatically.
The parent decomposes the task and dispatches Codex invocations for each piece.
Results flow back to the parent agent, which synthesizes them.

This approach gives you full control over orchestration — parallel execution, custom error handling, result aggregation — at the cost of building the orchestration layer yourself. It is appropriate for teams building repeatable agentic workflows, CI/CD pipelines, or automated code review systems, not for ad-hoc interactive use.

A minimal example of this pattern:

from agents import Agent, Runner
import subprocess

def run_codex(task: str) -> str:
    result = subprocess.run(
        ["codex", "--quiet", "--json", task],
        capture_output=True, text=True
    )
    return result.stdout

# Define tools that wrap Codex invocations
# The parent agent orchestrates multiple Codex calls

The Agents SDK handles the orchestration primitives — deciding when to dispatch, collecting results, managing failures. Codex handles the actual coding work within each invocation.

Practical Examples of Delegation

Research before implementation. Run a Codex session to investigate, then use the findings in a second session to implement.

# Session 1: Research
codex "Analyze how error handling is done across this codebase. List every pattern you find with file locations and examples. Write your findings to /tmp/error-handling-analysis.txt"

# Session 2: Implement (after reviewing the analysis)
codex "Based on the error handling patterns documented in /tmp/error-handling-analysis.txt, add consistent error handling to src/api/orders.ts"

The file system acts as the context bridge between sessions. The first session writes findings to a file; the second session reads them. This is explicit and inspectable — you can review the analysis before proceeding.

Parallel file modifications. Use git branches to isolate parallel work.

# Create branches for each task
git checkout -b feat/validate-users
codex "Add input validation to POST /api/users"
git add -A && git commit -m "Add user endpoint validation"

git checkout main
git checkout -b feat/validate-orders
codex "Add input validation to POST /api/orders"
git add -A && git commit -m "Add order endpoint validation"

# Merge branches
git checkout main
git merge feat/validate-users
git merge feat/validate-orders

This is more manual than Claude Code's worktree isolation, but it achieves the same goal: isolated file systems for parallel work, with git handling the merge.

Review as a separate session. After implementation, run a fresh Codex session specifically for review.

# After making changes, get a fresh-eyes review
codex "Review the changes in the current git diff. Check for bugs, security issues, missing edge cases, and style inconsistencies. Do not make any changes — just report findings."

The fresh session provides the same benefit as a sub-agent review in Claude Code: a clean context without the assumptions that built up during implementation.

Limitations Compared to Claude Code

Be clear-eyed about what Codex CLI does not do in this area:

No in-session sub-agents. The running Codex agent cannot spawn a child agent within the same session. It cannot delegate a piece of work to a focused sub-agent while continuing to think about the broader task.

No built-in parallel execution. Codex works sequentially within a session. Parallelism requires multiple sessions, which you orchestrate.

No automatic context passing between sessions. When you run multiple Codex sessions, each starts fresh. There is no built-in mechanism for one session to pass context to another. You handle this through files, git branches, or your own orchestration layer.

No sub-agent types. Codex does not have the concept of explore agents, plan agents, or custom agent types. Every session is a general-purpose agent. You shape its behavior through your prompt, not through a type system.

No SendMessage equivalent. You cannot continue a previous Codex session with follow-up instructions. Each codex invocation is independent. If you need follow-up work, you start a new session with appropriate context.

Workarounds for Missing Features

The limitations are real but not insurmountable. Here are practical workarounds.

For context isolation: use the file system. Write intermediate results to files. A research session writes findings to a temp file; an implementation session reads that file. This is more explicit than automatic context passing, which can be an advantage — you see exactly what context is being shared.

For parallelism: use shell parallelism. Run multiple Codex sessions in parallel using background processes, tmux panes, or separate terminals. You manage the coordination, but you get true parallelism.

For agent types: use prompt engineering. Instead of selecting an agent type, write your prompt to shape the agent's behavior. "Investigate and report without making changes" produces explore-like behavior. "Design an implementation plan before writing any code" produces plan-like behavior.

For sub-agent orchestration: use the Agents SDK. If you need programmatic orchestration, build it with the OpenAI Agents SDK. This is more work upfront but gives you full control.

Using Multiple Codex Sessions as a Manual Sub-Agent Pattern

The most practical sub-agent pattern for day-to-day Codex use is the manual multi-session approach. You act as the parent agent: you decompose the task, dispatch sessions, and synthesize results.

The workflow:

Decompose the task yourself. Identify the independent pieces.
Write a clear prompt for each piece. Each prompt should be self-contained — do not assume the session knows anything about the other sessions.
Run sessions in parallel. Use separate terminals or background processes.
Review each session's output independently.
Integrate the results. Merge branches, resolve conflicts, verify consistency.

This is more manual than Claude Code's sub-agent system, but it has advantages: you have full visibility into each session's work, you control the decomposition, and you can intervene at any point. For developers who prefer tight control over their agentic workflows, this is often the preferred approach regardless of which tool they use.

The key discipline is writing good prompts for each session. Since there is no parent agent writing handoff prompts for you, you must do this yourself. Make each prompt specific, complete, and self-contained. Reference specific files and patterns. Describe the expected output. Include constraints. Everything from Module 03 about prompt quality applies here, multiplied by the number of sessions you are managing.

The Agentic Developer's Playbook

title: "Sub-Agents — Codex CLI" tested_with: codex-cli: "0.2.x" last_updated: 2026-03-21 status: proven difficulty: intermediate prerequisites: [03-prompting-for-agents]