Sub-Agents (Codex CLI)

In Codex CLI there is no first-class concept called sub-agents like in OpenAI Codex. Instead, Codex offers two patterns that map closely:

1. Manual orchestration — splitting tasks explicitly across CLI or Cloud jobs.
2. Custom agents — building specialized AGENTS.md definitions with scoped tools and prompts.

OpenAI documentation confirms Codex agents can be guided by AGENTS.md and extended with tools via MCP servers. Each invocation (local or cloud) runs in its own containerized or session-bound context.

---

Manual orchestration

The most direct analogue to "manual sub-agents" is to launch multiple Codex tasks in parallel, either locally or in the cloud:

# Local CLI jobs
codex exec "Analyze security of src/auth.ts"
codex exec "Review performance of cache system"
codex exec "Check types in src/utils.ts"

Or with Cloud:

• Create three background tasks, each scoped to a different file.
• Each runs in a separate container, ensuring independence and no shared state.

Benefits:

• Explicit control over which job does what.
• Predictable and reproducible (each run is isolated).

Drawbacks:

• Manual orchestration overhead.
• All jobs inherit the same default agent configuration unless you override model/tools.

---

Custom agents

For recurring roles, Codex supports specialized agents defined in AGENTS.md. OpenAI calls this "a README for agents" — a file that constrains scope, defines invariants, and can adjust system-level behavior.

Example AGENTS.md snippet:

---
name: security-reviewer
description: Specialist for authentication and authorization code audits
tools:
  - read
  - grep
  - bash
model: gpt-5-codex
---

You are a security engineer focusing on authentication vulnerabilities.
Always highlight potential risks, remediation steps, and add rollback guidance.

Benefits:

• Automatic activation when context matches the role.
• Isolated contexts: each agent can have its own model and tool selection.
• Reusable across projects — check the agent into version control and share with your team.

Drawbacks:

• Setup overhead (authoring and maintaining AGENTS.md).
• More complex configuration when you need many roles.

---

Decision framework

Use manual orchestration when:

• You need quick, one-off analysis.
• Tasks are non-destructive (reads/searches).
• You want explicit control over what happens in each job.
• No time for setup overhead.

Use custom agents when:

• You need specialized expertise across multiple projects (e.g. security, performance, UX).
• Domain-specific tool access is important (e.g. Read/Grep only).
• You want automatic delegation based on context.
• Team-wide reuse and standardization are goals.

---

Building your agent arsenal

Over time you can create a library of AGENTS.md roles — security reviewers, performance optimizers, doc checkers — and standardize them across teams. Each project starts with a ready-made toolkit of agents that Codex can use directly.

---

Orchestrated intelligence

Modern Codex workflows combine manual parallelism (CLI + Cloud jobs) with custom reusable agents (AGENTS.md). Think of it as running a high-performance dev team: some jobs are quick ad-hoc reviews, others are handled by seasoned specialists you've already onboarded.

---

Sources

• Codex CLI docs — approvals, exec, and session behavior.
• Introducing Codex (OpenAI) — AGENTS.md as project guidance.
• Codex Cloud docs — background, parallel sandboxed containers.