What Are Sub-Agents in OpenAI Codex?

Mar 3, 2026

I had 10 tasks to complete for a feature. Running them one by one took 30-40 minutes. Then I discovered sub-agents in OpenAI Codex, and the same work finished in about 10 minutes.

The Problem with Sequential Execution

When I work on a feature, I often need to do multiple things:

Review my code changes
Run security checks
Check for type errors
Run linting
Write tests
Generate documentation

Without sub-agents, Codex does these tasks one after another. Each task waits for the previous one to finish. This adds up fast.

For example, when I added authentication to an API, I had these tasks:

Review auth logic for security issues
Check input validation
Test password hashing
Verify token generation
Review error handling

Running these sequentially meant I waited 3-4 minutes per task. Total time: about 20 minutes of waiting.

Sub-Agents: Running Tasks in Parallel

Sub-agents let Codex spawn multiple agents to work on independent tasks at the same time. Instead of waiting for one task to finish before starting the next, Codex launches several agents in parallel.

Here’s the difference:

Sequential execution:
Task 1 (3 min) -> Task 2 (3 min) -> Task 3 (3 min) -> Task 4 (3 min) -> Task 5 (3 min)
Total: 15 minutes

Parallel execution with sub-agents:
Task 1 (3 min) ┐
Task 2 (3 min) ├-> All complete together
Task 3 (3 min) │
Task 4 (3 min) │
Task 5 (3 min) ┘
Total: 3-4 minutes

When I ran those 5 auth review tasks with sub-agents enabled, they finished in under 4 minutes instead of 15.

How to Enable Sub-Agents

You have three options to enable sub-agents in Codex.

Option 1: Use /experimental

Type this in your Codex prompt:

/experimental

Then ask Codex to run multiple tasks. It will automatically parallelize them when possible.

Option 2: Configuration File

Create or edit your .codex/config.json file:

{
  "experimental": {
    "parallelAgents": true,
    "maxConcurrentAgents": 5
  }
}

The maxConcurrentAgents setting controls how many agents can run at once. I usually set it to 3-5 to avoid overwhelming my system.

Option 3: Direct Prompt

You can also just ask Codex directly in your prompt:

Use parallel sub-agents to:
1. Review my authentication code for security issues
2. Check all input validation
3. Test the password hashing implementation
4. Verify token generation logic
5. Review error handling

Codex will recognize the intent and spawn sub-agents for independent tasks.

Practical Example: Code Review

Let me show you a real example. I just finished writing a user registration API and wanted a comprehensive review.

Without sub-agents, I would ask for each review type separately. With sub-agents, I use one prompt:

Use parallel sub-agents to review my registration API:
1. Security review - check for injection vulnerabilities
2. Input validation review - verify all inputs are sanitized
3. Error handling review - ensure proper error messages
4. Test coverage check - identify missing tests
5. Documentation review - check for missing or unclear docs

Codex spawns 5 sub-agents that work simultaneously. Each agent focuses on its specific area and returns findings.

Here’s what the output looks like:

🤖 Spawning 5 parallel agents...

[Agent 1 - Security] Analyzing authentication flow...
[Agent 2 - Validation] Checking input sanitization...
[Agent 3 - Errors] Reviewing error handling...
[Agent 4 - Tests] Analyzing test coverage...
[Agent 5 - Docs] Checking documentation...

Results:
✓ Agent 1: Found 2 potential SQL injection points (lines 45, 78)
✓ Agent 2: Missing email validation in registration endpoint
✓ Agent 3: Error messages leak internal state in 3 places
✓ Agent 4: 72% coverage, missing edge case tests for password reset
✓ Agent 5: API docs missing rate limiting information

Total time: 4.2 minutes

All 5 perspectives in about 4 minutes instead of 15-20.

Practical Example: Parallel Implementation

Sub-agents also work for implementation tasks. I used this when building a feature that needed changes across multiple files.

I asked Codex:

Use parallel sub-agents to implement user preferences:
1. Add preferences table to database schema
2. Create preferences API endpoints
3. Add preferences UI components
4. Write tests for preferences feature
5. Update documentation

Each sub-agent worked on its part independently. Since the tasks didn’t depend on each other’s output, they all ran at the same time.

The implementation took 12 minutes instead of the 40+ minutes it would have taken sequentially.

When Parallel Execution Works (and When It Doesn’t)

Sub-agents work best when tasks are independent. Here’s what I’ve learned:

Good for Parallel Execution

Code reviews from different perspectives (security, performance, style)
Analysis tasks that read different files or systems
Independent implementations across separate modules
Testing different components or features

Bad for Parallel Execution

Dependent tasks where one task needs another’s output
Sequential operations like: create file -> write to it -> read from it
State-modifying tasks that might conflict with each other

Common Mistakes to Avoid

I made these mistakes when I started using sub-agents.

Mistake 1: Running Dependent Tasks in Parallel

I tried to run these tasks in parallel:

1. Create user schema
2. Add user API endpoints
3. Test user endpoints

This failed because task 2 needed the schema from task 1, and task 3 needed the endpoints from task 2.

Fix: Group dependent tasks together. Run the group in parallel with other independent groups.

Mistake 2: Not Using Plan Mode

When I give Codex a complex multi-task request, it sometimes struggles to identify which tasks can run in parallel.

Fix: I use plan mode first:

/plan

Review my codebase and create a plan to:
- Add authentication
- Add rate limiting
- Add input validation
- Add error logging

Identify which tasks can run in parallel.

Codex creates a structured plan showing dependencies:

Phase 1 (parallel):
├── Add authentication (independent)
├── Add rate limiting (independent)
└── Add input validation (independent)

Phase 2 (sequential, after Phase 1):
└── Add error logging (depends on auth for user context)

Then I can execute Phase 1 with parallel sub-agents, and Phase 2 after.

Mistake 3: Too Many Concurrent Agents

I once spawned 15 sub-agents for a massive codebase review. My system slowed to a crawl.

Fix: Limit concurrent agents to 3-5 in your config:

{
  "experimental": {
    "maxConcurrentAgents": 5
  }
}

Real-World Time Savings

Here’s what I’ve measured in my own work:

Task Type	Sequential	Parallel	Time Saved
5-point code review	18 min	4 min	78%
10 file refactoring	35 min	12 min	66%
Security audit (8 checks)	25 min	6 min	76%
Documentation update (6 files)	20 min	5 min	75%

The time savings add up quickly. In a typical day, I save 1-2 hours by using sub-agents for independent tasks.

Tips for Maximum Efficiency

Be explicit about parallelization. Don’t assume Codex will automatically parallelize. Tell it to use sub-agents.

Group related tasks. If you have 10 tasks but they fall into 3 logical groups, spawn 3 sub-agents instead of 10.

Use plan mode for complex work. Let Codex figure out the dependency graph before executing.

Monitor the first few runs. Watch how Codex distributes work across sub-agents. Adjust your prompts if needed.

Summary

In this post, I showed you how OpenAI Codex sub-agents can reduce your development time by running independent tasks in parallel. I covered three ways to enable sub-agents, practical examples for code review and implementation, and common mistakes to avoid.

The key insight is simple: tasks that don’t depend on each other should run at the same time, not one after another. Sub-agents make this automatic in Codex.

Start with small parallel tasks like running multiple code reviews. Once you’re comfortable, move to parallel implementations across different files. You’ll see the time savings immediately.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Multi-Agent Orchestration
👨‍💻 Slash Commands Guide
👨‍💻 Agents SDK

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!