Codex: Codex Subagents
Last updated: 2026-08-31
Subagents let Codex decompose complex tasks and delegate them to specialized agents for parallel execution, dramatically improving efficiency.
📋 Prerequisites: Understanding Codex workflow modes and Agent Skills
1. What You Will Learn
- Subagent concepts and working principles
- Task delegation strategies
- Parallel execution and coordination
- Subagent vs single-agent comparison
2. What Are Subagents
Subagents are auxiliary agents created by the main Codex Agent, each responsible for a subtask.
graph TB
A[Main Agent] --> B[Subagent 1: Frontend]
A --> C[Subagent 2: Backend]
A --> D[Subagent 3: Testing]
B --> B1[Modify UI Components]
C --> C1[Add API Endpoints]
D --> D1[Write Test Cases]
B1 --> E[Main Agent Aggregates]
C1 --> E
D1 --> E
| Feature | Description |
|---|---|
| Independent Execution | Each subagent has its own sandbox |
| Parallel Execution | Multiple subagents run simultaneously |
| Auto-coordination | Main Agent aggregates results |
| Specialized Division | Each subagent can use a different Skill |
3. Use Cases
(1) Multi-module Parallel Development
TEXT
📖 Display only
> Add product review functionality to the e-commerce site:
> - Frontend: review component + review list + star ratings
> - Backend: review API + rating aggregation
> - Testing: frontend and backend tests
# Codex automatically decomposes into subagents:
# Subagent 1: Frontend component development
# Subagent 2: Backend API development
# Subagent 3: Test writing
# Three subagents execute in parallel
(2) Multi-language Translation
TEXT
📖 Display only
> Translate README.md into Japanese, Portuguese, and Arabic
# Codex creates three subagents for parallel translation
# Subagent 1: en → ja
# Subagent 2: en → pt-br
# Subagent 3: en → ar
▶ Example 1: Alice's Multi-module Development
TEXT
📖 Display only
# Alice adds a complete payment feature
> Add Stripe payments:
> 1. Payment page UI
> 2. Payment API endpoint
> 3. Webhook handling
> 4. Order management
> 5. Tests for all modules
# Codex decomposes into 4 subagents:
🔄 Subagent 1: Payment page UI + order management page
🔄 Subagent 2: Payment API + Webhook endpoint
🔄 Subagent 3: Order model + database migration
🔄 Subagent 4: Integration tests
# Parallel execution, total ~15 minutes
# Serial execution would take ~50 minutes
4. Task Delegation Strategy
(1) Conditions for Parallelism
| Condition | Description |
|---|---|
| Modify different files | Subagents don't operate on the same file |
| No data dependencies | Subagents don't need to share state |
| Independently verifiable | Each subtask can be verified independently |
(2) When Not to Parallelize
| Situation | Description |
|---|---|
| Modify same file | May cause conflicts |
| Sequential dependencies | Later steps need earlier results |
| Shared database | May cause race conditions |
(3) Decomposition Principles
TEXT
📖 Display only
1. Decompose by functional module (frontend / backend / testing)
2. Decompose by file directory (src/auth/ / src/api/ / src/utils/)
3. Decompose by task type (implementation / testing / documentation)
4. Ensure clear boundaries for each subtask
5. Subagent Coordination
(1) Automatic Coordination
The Main Agent automatically manages the subagent lifecycle:
TEXT
📖 Display only
1. Analyze task, decompose into subtasks
2. Create subagent for each subtask
3. Assign independent sandbox environments
4. Monitor execution progress
5. Aggregate results, handle conflicts
6. Execute integration verification
(2) Result Merging
TEXT
📖 Display only
# After subagents complete, Main Agent merges results:
✅ Subagent 1: Frontend components done (3 files)
✅ Subagent 2: Backend API done (2 files)
✅ Subagent 3: Testing done (4 files)
# Main Agent runs integration tests
→ Running integration tests...
→ All 15 tests passed ✓
# Handle conflicts (if any)
→ No conflicts detected
→ Ready for review
6. Subagent vs Single Agent
| Dimension | Subagents | Single Agent |
|---|---|---|
| Execution Speed | Fast (parallel) | Slow (serial) |
| Resource Consumption | High (multiple sandboxes) | Low (single sandbox) |
| Coordination Complexity | High | Low |
| Conflict Risk | Present | None |
| Best For | Independent subtasks | Tasks with dependencies |
❓ FAQ
Q Are subagents created automatically?
A In App/Web versions, Codex automatically creates subagents based on task complexity. In CLI, you need to explicitly specify or trigger via Skills.
Q Is there a limit on subagent count?
A Depends on your subscription plan. Free: max 1, Plus: max 3, Pro: max 10, Business: max 20.
Q How do subagents communicate with each other?
A Subagents coordinate through the Main Agent, not directly. The Main Agent collects results and decides next steps.
Q Does one subagent failure affect others?
A No. Each subagent runs independently. Single failure doesn't affect others. The Main Agent handles failed subtasks.
Q How do I manually create subagents?
A Explicitly decompose the task in the Prompt, and Codex will recognize and create subagents. You can also use Skills to define subagent workflows.
📖 Summary
- Subagents are auxiliary agents created by the Main Agent, running independently
- Use cases: multi-module parallelism, multi-language translation, batch processing
- Decomposition principles: by module/directory/type, ensure clear boundaries
- Main Agent auto-coordinates, aggregates results, handles conflicts
- Parallelism speeds up but increases resource consumption and conflict risk
📝 Exercises
- Basic (⭐): Have Codex automatically decompose a medium-complexity task into subagents for execution.
- Intermediate (⭐⭐): Design a multi-module feature ensuring each module can be developed in parallel, observe subagent execution.
- Advanced (⭐⭐⭐): Compare the same task using single-agent serial vs subagent parallel execution, write a performance report.
