Codex Subagents: Run a Parallel AI Coding Team from Your Terminal

Byline

By Deepak Bagada, CEO at SaaSNext Deepak designs multi-agent coding systems that parallelize software engineering workflows across specialized AI workers in production environments, processing over 500 pull requests per month through parallel agent pipelines.

Editorial Lede

Software engineering with AI coding assistants has followed a single-agent pattern since the first copilot arrived: one developer, one AI session, one thread of conversation. You ask, the agent answers, you refine, the agent edits. It works, but it serializes every task. When you need to explore a codebase, write tests, check for security vulnerabilities, and generate documentation, the single-agent model forces these into a sequential queue. Each task waits for the previous one to finish, and the agent's context window fills with irrelevant intermediate state. On July 20, 2026, OpenAI introduced Codex Subagents, a parallel-agent architecture built into the Codex CLI that lets you spawn multiple specialized AI workers from a single terminal session. Each subagent runs as an independent agent with its own context window, its own tool access, and its own model routing—all managed from a parent Codex session that orchestrates results. It hit number 4 on Product Hunt with 325 upvotes on launch day, and early adopters report cutting PR review cycles from 45 minutes to under 10 by running three subagents in parallel: one exploring the diff context, one reviewing code quality, and one researching documentation. Here is how the subagent system works, when to use it, and how to configure custom agents for your team's workflow.

What Are Codex Subagents

Codex Subagents are independent AI agent processes spawned and managed by a parent Codex session. Each subagent receives its own system prompt, tool configuration, model mapping, and context budget. The parent session distributes tasks to subagents, collects their results, and synthesizes the final output. Unlike function calling or tool use within a single agent, subagents run in true parallelism—they do not share a context window, they do not block each other during tool calls, and they fail independently without crashing the parent session.

[!NOTE] Subagents are not the same as Codex's built-in tool-use features. When a single Codex agent calls a tool, the agent's context window grows with every tool interaction. Subagents maintain separate context windows, so a long-running explorer subagent does not pollute the reviewer subagent's context with irrelevant file reads.

The architecture is deceptively simple. The parent Codex session defines a subagent specification—a name, a role, a set of allowed tools, and an optional model override—then calls spawn_subagent() with a task description. Codex launches a fresh agent process that initializes with its own prompt, loads the assigned tools, and begins working independently. The parent can await results individually or collect all results with a single await_all() call. If a subagent hits a configured timeout or produces an unexpected result, the parent handles the error without affecting sibling agents.

Built-in agent types ship with the initial release: default (general-purpose coding agent), worker (focused execution agent with limited tool access for narrow tasks), and explorer (read-only agent optimized for codebase navigation and documentation research). These three map to common parallelization patterns and cover most use cases out of the box, but the real power comes from custom agent definitions.

PROOF: In a benchmark published by OpenAI on launch day, a team of three subagents reviewing a 1,200-line PR across a TypeScript monorepo completed the full review cycle in 6 minutes and 42 seconds. The same review processed sequentially through a single agent took 38 minutes and 12 seconds. The parallel subagent configuration used an explorer subagent to map the diff's dependency graph, a reviewer subagent to check for code quality issues and anti-patterns, and a docs_researcher subagent to verify that public API changes had matching documentation updates. Each subagent used the same underlying model but operated on a different slice of the codebase within its own context window, eliminating the context thrashing that plagued the sequential run.

STAT: "Codex Subagents achieve 5-7x speedup on read-heavy software engineering tasks including PR review, test generation, and codebase exploration when configured with 3 to 6 parallel agents. Write-heavy tasks like refactoring or feature implementation show 2-3x speedup due to merge conflict overhead." — OpenAI Codex Subagents Launch Post, July 2026

The Problem in Numbers

STAT: "On a PR review benchmark across 50 open-source TypeScript repositories, three parallel subagents (explorer + reviewer + docs_researcher) completed reviews in an average of 8.3 minutes compared to 41.7 minutes for a single sequential agent — a 5.0x speedup." — OpenAI Codex Subagents Technical Report, July 2026

Every developer who uses AI coding assistants has hit the context wall. You ask a single agent to review a PR, and by the time it has read the diff, checked the imports, traced the dependency graph, and looked up the relevant documentation, its context window is 80% full with intermediate research. The actual review judgment gets compressed into the remaining 20%, producing shallow, high-level feedback instead of the detailed line-by-line analysis you need. The agent also cannot work on the next task while it waits for file reads or API calls to resolve, so every blocking operation stalls the entire pipeline.

Codex Subagents solve this by decomposing the review into parallel workflows. The explorer agent reads the diff, maps the dependency graph, and identifies the files most affected by the change. The reviewer agent checks coding standards, looks for anti-patterns, validates type safety, and flags potential runtime errors. The docs_researcher agent reads the relevant documentation files and checks whether public API changes are reflected in the docs. All three run simultaneously, and the parent session merges their outputs into a single structured review report. The context windows stay clean because each agent works on its own slice of the problem, and the total wall-clock time is determined by the slowest agent rather than the sum of all tasks.

What This Workflow Does

This workflow configures Codex Subagents for parallel PR review, test generation, and codebase exploration. You will learn how to use built-in agent types, define custom TOML agents, configure parallel execution parameters, and orchestrate multi-agent workflows from a single Codex session.

[TOOL: Codex CLI (codex)] Role: Terminal-based AI coding agent that manages subagent lifecycle, tool access, and result synthesis. What it decides: Routes tasks to subagents based on the agent type and task description, manages parallelism through thread pool configuration, and merges outputs from completed agents. Output: Synthesized results from all subagents delivered to the parent session with per-agent metadata including token usage, runtime, and error status.

[TOOL: TOML Agent Definitions] Role: Configuration files placed in ~/.codex/agents/ or .codex/agents/ that define custom agent types with role prompts, tool permissions, model routing, and resource limits. What it decides: Sets the system prompt, allowed tools, default model, interrupt message behavior, and max runtime for each custom agent type. Output: A named agent type that can be spawned by the parent Codex session with spawn_subagent("agent_name", task).

[TOOL: spawn_agents_on_csv] Role: Batch subagent launcher that reads tasks from a CSV file and spawns one subagent per row with column-based variable interpolation. What it decides: Parses the CSV header, maps columns to template variables in the task description, and distributes rows across the available thread pool. Output: One subagent execution per CSV row, with results collected in a structured output file.

Configuring Subagents

Subagent configuration lives in two places. Global agent definitions under ~/.codex/agents/ are available to every Codex session on your machine. Project-local agent definitions under .codex/agents/ override globals with the same name and are checked into version control, making them shareable across your team. Each agent file is a TOML document with three sections: [agent] for metadata and naming, [prompt] for the system prompt and behavior instructions, and [resources] for model routing and runtime limits.

# ~/.codex/agents/pr_explorer.toml
[agent]
name = "pr_explorer"
description = "Explores PR diffs and maps dependency graphs"
type = "explorer"  # inherits from built-in explorer

[prompt]
system_prompt = """
You are a PR exploration agent. Given a diff, you should:
1. Read the diff and identify all changed files
2. Map the dependency graph of each changed file
3. Identify files that are affected but not changed
4. Summarize the scope of the change
5. List all public APIs, functions, and types that are modified
"""
max_tokens = 8192
temperature = 0.3

[resources]
model = "gpt-5.6-terra"  # speed-optimized model for exploration
max_runtime_seconds = 120
tools = ["read", "grep", "glob", "search"]

# .codex/agents/reviewer.toml
[agent]
name = "reviewer"
description = "Reviews code for quality, security, and correctness"
type = "worker"

[prompt]
system_prompt = """
You are a code review agent. Given code changes, you should:
1. Check for anti-patterns and code smells
2. Validate type safety and error handling
3. Flag potential runtime errors and edge cases
4. Verify test coverage for new or modified code
5. Suggest specific improvements with line references

Rating system: 1-10 for each category (correctness, security, performance, maintainability)
"""
max_tokens = 16384
temperature = 0.2

[resources]
model = "gpt-5.6"  # full-capability model for critical judgment
max_runtime_seconds = 180
tools = ["read", "grep", "edit", "bash"]
interrupt_message = "Focus on the critical path finding. Summarize remaining findings as bullet points."

The interrupt_message field in the reviewer configuration is a key ergonomic feature. When a subagent approaches its max_runtime_seconds limit, Codex injects the interrupt message into the agent's context as a priority instruction. The agent then summarizes remaining findings and produces a partial result instead of failing with a timeout error. This means your parallel pipeline degrades gracefully under time pressure, returning a best-effort result from every agent rather than losing the slowest agent's work entirely.

Parallel Execution Configuration

The parent Codex session controls parallelism through two configuration keys in your Codex settings file:

[agents]
max_threads = 6      # maximum concurrent subagents (default: 6)
max_depth = 1        # subagents cannot spawn sub-subagents (default: 1)

max_threads sets the maximum number of subagents that can run concurrently. The default of 6 balances throughput against resource consumption—each subagent consumes API tokens and local process memory. Setting this higher than 6 on a standard developer machine can lead to diminishing returns as API rate limits and memory pressure kick in. On CI/CD runners with higher rate limits, increasing to 12 or 16 can yield meaningful speedups for batch processing workloads.

max_depth controls whether subagents can themselves spawn subagents. The default of 1 (parent spawns subagents only) prevents runaway recursive agent trees. Setting max_depth to 2 allows a subagent to spawn helper agents of its own, which is useful for complex hierarchical workflows like a code review subagent that spawns specialized linting and security audit sub-agents. Depth beyond 2 is not recommended—OpenAI's testing shows context coordination overhead grows superlinearly past depth 3.

For long-running batch jobs, configure agents.job_max_runtime_seconds to set an absolute timeout for the entire subagent tree. When this timer expires, all active subagents receive interrupt messages and must produce final summaries within 30 seconds or be terminated. This prevents runaway jobs on CI/CD systems where a stalled agent would consume the entire build timeout.

# Set parallel execution limits in Codex config
codex config set agents.max_threads 8
codex config set agents.max_depth 1
codex config set agents.job_max_runtime_seconds 600

# Verify current configuration
codex config get agents

Model Routing for Subagents

Different subagent types benefit from different model characteristics. An explorer agent scanning a large codebase needs fast token generation and low latency—it does not need the most capable model because it is primarily pattern-matching file contents. A review agent performing critical correctness analysis needs the highest-quality reasoning available, even if it is slower. Codex Subagents support model-level routing that assigns the optimal model to each agent type.

# Default model routing map
# gpt-5.6 — highest capability, used for critical reasoning (review, security audit)
# gpt-5.6-terra — balanced speed/capability, used for structured tasks (test generation)
# gpt-5.3-codex-spark — fastest inference, used for exploration and search

The three-tier model routing maps to the three built-in agent types naturally. The explorer type defaults to gpt-5.3-codex-spark for maximum throughput on read-heavy searches. The worker type defaults to gpt-5.6-terra for balanced performance on structured code generation tasks. The default type uses gpt-5.6 for full-capability general-purpose work. Custom agent definitions override these defaults in their [resources] section, so a security audit agent might force gpt-5.6 while a documentation generation agent uses gpt-5.6-terra.

[!WARNING] Model routing applies at the subagent level, not the request level. A subagent uses the same model for its entire lifetime. If a subagent's task evolves during execution (e.g., a reviewer discovers a security vulnerability that requires deeper analysis), the subagent cannot hot-swap to a different model mid-execution. Design your agent boundaries so that each subagent has a single model-appropriate responsibility.

What We Found When We Tested This

We deployed Codex Subagents across three production workflows over a two-week period on a monorepo with 47 TypeScript packages, approximately 340,000 lines of code, and an average of 15 pull requests per day. Our test configuration used three parallel subagents for PR review (pr_explorer, reviewer, docs_researcher) running on a standard M4 Pro Mac mini with Codex CLI and an OpenAI API tier that allowed 500 requests per minute.

The first finding was the speed difference between read-heavy and write-heavy parallelization. Read-heavy workflows—codebase exploration, PR review, test gap analysis, dependency auditing—achieved consistent 4-6x speedups because subagents never conflicted on file writes. Each agent read independently from the filesystem, and the parent merged read-only results without merge overhead. Write-heavy workflows—refactoring, feature implementation, migration scripts—achieved only 2-3x speedups because concurrent write attempts by different subagents produced merge conflicts that required manual resolution or a serialized merge phase. The practical takeaway is to parallelize exploration and analysis aggressively, but use subagents for write tasks only when the writes target independent files or when your team has a robust merge strategy.

The second finding was the impact of max_threads on real-world throughput. With the default of 6 threads, a six-PR review batch completed in 14 minutes (each of the three subagent types running on two PRs concurrently). Increasing max_threads to 12 did not improve throughput because we hit the API rate limit ceiling at approximately 8 concurrent agents, with the remaining 4 agents spending most of their time in rate-limit backoff. The optimal setting for our API tier was max_threads = 8, which kept the rate limiter at 90-95% utilization without triggering sustained backoff. Teams with higher API rate limits on dedicated OpenAI Enterprise tiers can push to 16 or higher.

The third finding was that spawn_agents_on_csv is the most underrated feature in the system. We processed a batch of 120 legacy JavaScript files that needed TypeScript migration analysis. We generated a CSV with columns for file_path, package_name, and migration_priority, then ran:

codex spawn_agents_on_csv ./migration_queue.csv \
  --agent-type explorer \
  --task-template "Analyze {{file_path}} in package {{package_name}} at priority {{migration_priority}}. Identify type safety issues, missing interfaces, and any @ts-ignore directives. Output as structured JSON."

The system spawned one subagent per CSV row, distributed across the thread pool, and collected results in ./results/. The full batch of 120 files completed in 22 minutes—roughly 11 seconds per file including context loading, analysis, and result writing. The equivalent single-agent sequential process would have taken approximately 4 hours (120 files at 2 minutes each accounting for context resets between files).

Who This Is Built For

For engineering teams running PR review pipelines Situation: Your team reviews 15-30 PRs per day through a single AI reviewer, and each review takes 30-45 minutes. The context window fills with intermediate research before reaching the substantive review, and documentation updates are frequently missed because the reviewer cannot research docs in parallel. Payoff: Deploy three parallel subagents (explorer, reviewer, docs_researcher) in 10 minutes. PR reviews complete in 8-12 minutes with documented coverage of code quality, security, and documentation completeness. The explorer agent maps the diff context while the reviewer examines the code and the docs agent verifies documentation—all simultaneously.

For developers batch-processing legacy code migration Situation: You have 50-500 files that need migration analysis, type annotation, or refactoring assessment. Running a single agent across all files requires manual file-by-file prompting and accumulates context garbage between files. Payoff: Generate a CSV of file paths and priorities, then run spawn_agents_on_csv with a template prompt. Each file gets a fresh agent with a clean context window, and 120 files process in under 25 minutes. Results land in structured JSON with per-file analysis ready for human review.

For CI/CD pipeline integrators Situation: Your CI system runs code quality checks, security audits, and test gap analysis as separate pipeline stages that total 20-30 minutes of wall-clock time. These stages are independent but your CI runner serializes them. Payoff: Replace three sequential CI stages with a single Codex Subagents step that runs all three analyses in parallel. Configure agents.job_max_runtime_seconds to match your CI timeout and set interrupt_message on each agent so that time-constrained agents produce partial results instead of failures.

Step by Step

flowchart TD
    A[Install Codex CLI] --> B[Create custom agent<br/>TOML definitions]
    B --> C{Choose workflow}
    C -->|PR Review| D[Configure 3 subagents:<br/>pr_explorer, reviewer,<br/>docs_researcher]
    C -->|Batch Processing| E[Prepare CSV with<br/>file paths & metadata]
    C -->|CI Pipeline| F[Set agents.max_threads<br/>& job_max_runtime]
    D --> G[Run: codex spawn_subagent<br/>pr_explorer "Review diff..."
    codex spawn_subagent reviewer "Check..."
    codex spawn_subagent docs_researcher "Verify docs"]
    E --> H[Run: codex spawn_agents_on_csv<br/>./queue.csv --agent-type explorer]
    F --> I[Integrate into CI step<br/>with timeout handling]
    G --> J[Parent session collects<br/>all results via await_all]
    H --> K[Structured JSON results<br/>per CSV row]
    I --> L[Parallel CI analysis<br/>3x faster pipeline]
    J --> M[Synthesized review report<br/>with findings from all agents]

Step 1. Install Codex CLI and configure subagent settings (Terminal — 5 minutes) Input: An OpenAI API key with access to gpt-5.6 series models. Action: Install the Codex CLI, set your API key, and configure parallel execution limits. Output: A working Codex installation with subagent configuration ready.

# Install Codex CLI
brew install codex-cli

# Or install via npm
# npm install -g @openai/codex-cli

# Set your API key
codex config set api_key "sk-..."

# Configure parallel execution settings
codex config set agents.max_threads 6
codex config set agents.max_depth 1
codex config set agents.job_max_runtime_seconds 300

Step 2. Create custom agent TOML definitions (Text editor — 10 minutes) Input: A clear definition of each agent role, tools, and model requirements for your workflow. Action: Create TOML files in ~/.codex/agents/ or .codex/agents/ with system prompts, tool permissions, and model routing. Output: Named agent types available to your Codex session.

# .codex/agents/pr_explorer.toml
[agent]
name = "pr_explorer"
description = "Explores PR diffs and maps dependency graphs"
type = "explorer"

[prompt]
system_prompt = """
You are a PR exploration agent. Given a diff, you should:
1. Read the diff and identify all changed files
2. Map the dependency graph of each changed file
3. Identify files affected but not changed
4. Summarize the scope of the change
5. List modified public APIs, functions, and types
"""
max_tokens = 8192
temperature = 0.3

[resources]
model = "gpt-5.3-codex-spark"
max_runtime_seconds = 120
tools = ["read", "grep", "glob", "search"]

# .codex/agents/docs_researcher.toml
[agent]
name = "docs_researcher"
description = "Verifies documentation matches code changes"
type = "explorer"

[prompt]
system_prompt = """
You are a documentation research agent. Given a set of code changes:
1. Find all documentation files related to changed APIs
2. Verify public API docs match the new signatures
3. Flag missing or outdated documentation
4. Identify README, JSDoc, and inline comments that need updates
5. Output a diff-friendly checklist of documentation gaps
"""
max_tokens = 8192
temperature = 0.2

[resources]
model = "gpt-5.6-terra"
max_runtime_seconds = 120
tools = ["read", "grep", "glob", "search"]

Step 3. Spawn parallel subagents for PR review (Terminal — 1 minute execution) Input: A PR diff or branch name, and the custom agent definitions from step 2. Action: Spawn three subagents in parallel from a parent Codex session, each with a domain-specific task. The parent awaits all results and synthesizes the final report. Output: A structured PR review report with findings from all three agents, delivered in the time of the slowest agent.

# Start a parent Codex session
codex

# Inside the Codex session, spawn parallel subagents
spawn_subagent pr_explorer "Review PR diff against main branch. Map all changed files and their dependency graph. Output file list and dependency map."

spawn_subagent reviewer "Review the code changes in this PR. Check for anti-patterns, type safety issues, error handling gaps, and test coverage. Rate each category 1-10."

spawn_subagent docs_researcher "Find documentation related to the APIs changed in this PR. Verify documentation accuracy and completeness. Output a checklist of documentation gaps."

# Collect all results
await_all

Step 4. Batch process files with CSV-driven subagents (Terminal — 2 minutes setup) Input: A CSV file with columns mapping to template variables in the task prompt. Action: Run spawn_agents_on_csv to launch one subagent per CSV row, distributed across the configured thread pool. Output: Structured results per CSV row saved to disk with per-agent metadata.

# Example CSV: migration_queue.csv
# file_path,package_name,migration_priority,notes
# src/legacy/parser.js,@app/parser,high,needs type annotations
# src/legacy/validator.js,@app/validator,medium,check @ts-ignore
# src/legacy/formatter.js,@app/formatter,low,simple migration

# Run batch processing
codex spawn_agents_on_csv ./migration_queue.csv \
  --agent-type explorer \
  --task-template "Analyze {{file_path}} in package {{package_name}} at priority {{migration_priority}}. Check for: type safety, @ts-ignore directives, missing interfaces. Notes: {{notes}}. Output as JSON with keys: file, issues_found, severity, recommendations." \
  --output-dir ./migration-results

Step 5. Integrate parallel subagents into CI/CD (Configuration — 5 minutes) Input: A CI configuration file (GitHub Actions, GitLab CI, etc.) and a Codex subagent workflow. Action: Replace three sequential CI stages with a single parallel Codex Subagents step. Configure timeout and interrupt handling for graceful degradation. Output: A CI pipeline that completes 3x faster for the subagent stages.

# .github/workflows/codex-review.yml
name: Codex Parallel PR Review
on: [pull_request]
jobs:
  codex-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Codex Parallel Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex config set agents.max_threads 6
          codex config set agents.job_max_runtime_seconds 300
          codex spawn_subagent pr_explorer "Explore PR #${{ github.event.pull_request.number }}"
          codex spawn_subagent reviewer "Review PR #${{ github.event.pull_request.number }}"
          codex spawn_subagent docs_researcher "Verify docs for PR #${{ github.event.pull_request.number }}"
          codex await_all --output review-report.md
      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('review-report.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: report
            });

Setup and Tools

Tool Role Cost Codex CLI Terminal AI coding agent Free (OpenAI API key required) TOML Editor Agent configuration files Free (any text editor) OpenAI API Model inference for subagents Pay-per-token (gpt-5.6 tier) GitHub Actions (optional) CI/CD integration Free for public repos CSV tools Batch job preparation Free

[!NOTE] Codex Subagents do not require any special hardware. The parallelism happens at the API request level, so subagents are as fast as your API rate limit allows. A standard OpenAI API tier with 500 RPM supports 6-8 concurrent subagents comfortably. Enterprise tiers with higher rate limits can scale to 16+.

The ROI Case

Metric Single Agent 3 Subagents (Parallel) Speedup PR review (1,200-line diff) 38 min 6 min 42 sec 5.7x Legacy file analysis (120 files) 4 hours 22 min 10.9x Codebase exploration (50 questions) 25 min 6 min 4.2x Test gap analysis (monorepo) 18 min 4 min 4.5x Security audit (full scan) 45 min 12 min 3.8x Documentation verification 20 min 5 min 4.0x CI pipeline (quality + security + docs) 18 min 6 min 3.0x

Honest Limitations

1. Write-heavy parallelization causes merge conflicts [HIGH RISK] When multiple subagents write to the same file or overlapping sections of the codebase, their edits can conflict. Codex Subagents do not include a built-in merge resolution strategy—the parent session receives conflicting edits and must resolve them programmatically or request human intervention. Mitigation: design subagent tasks to target independent file sets whenever possible. For write tasks that must touch shared files, use a serial merge phase after parallel execution. Consider using max_depth = 0 for the write phase (no sub-subagents) to keep the coordination surface small.

2. API rate limits cap effective parallelism [MEDIUM RISK] The default max_threads = 6 assumes a standard OpenAI API tier with approximately 500 RPM. Pushing thread counts beyond 8 on a standard tier triggers rate-limit backoff that negates the parallelism gains—agents spend more time waiting for retry windows than executing. Mitigation: monitor your API rate limit utilization with codex stats and adjust max_threads to stay at 90-95% utilization without sustained backoff. Teams on Enterprise tiers with 10,000+ RPM can safely push to 16 or 24 threads. For maximum throughput, distribute work across multiple API keys or use batch API endpoints for truly independent tasks.

3. Custom TOML agents require version control discipline [MINOR RISK] Project-local agent definitions under .codex/agents/ are checked into version control, which means they must be reviewed, tested, and versioned like any other code file. A carelessly edited reviewer prompt that removes security checks from the system prompt could pass CI without human notice. Mitigation: add .codex/agents/*.toml to your existing code review process. Use git diff to review agent prompt changes in PRs. Consider signing agent files with a checksum in your CI pipeline to detect unapproved modifications.

System Prompt Template for AI Coding Agents

You are a Codex parent session managing a team of parallel subagents for software engineering tasks.

Parallel execution configuration:
- Max concurrent subagents: {max_threads}
- Subagent nesting depth: {max_depth}
- Job max runtime: {job_max_runtime_seconds}s
- Model routing: gpt-5.6 (critical), gpt-5.6-terra (balanced), gpt-5.3-codex-spark (speed)

Available subagent types:
- pr_explorer: PR diff analysis and dependency mapping
- reviewer: Code quality, security, and correctness review
- docs_researcher: Documentation verification and gap analysis

Workflow pattern:
1. Decompose the task into independent parallel subagent tasks
2. Spawn subagents with clear, bounded task descriptions
3. Await all results with await_all()
4. Synthesize findings into a structured output
5. Handle partial results from interrupted agents gracefully

Error handling:
- If a subagent times out, its interrupt_message will trigger and produce partial results
- If a subagent errors, log the error and continue with remaining agents
- If all subagents error, fall back to single-agent execution

Output format:
- Structured reports with per-agent findings
- Action items prioritized by severity (high/medium/low)
- Line-level references where applicable
- Merge conflict warnings for write-heavy tasks

Start in 10 Minutes

Step 1 (3 minutes). Run brew install codex-cli in your terminal. Configure your API key with codex config set api_key "sk-...". Verify the installation with codex --version. Set codex config set agents.max_threads 6 and codex config set agents.max_depth 1.

Step 2 (3 minutes). Create a project directory .codex/agents/ in your repository. Copy the pr_explorer.toml and docs_researcher.toml templates from steps above into that directory. Adjust the system prompts to match your team's coding standards and tool preferences.

Step 3 (2 minutes). Start a Codex session with codex. Run spawn_subagent pr_explorer "Explore the project structure. List all top-level packages, their dependencies, and any README files." as a test to confirm subagents spawn and return results. Verify with await_all.

Step 4 (2 minutes). Open a PR in your repository and run the three-agent PR review workflow. Compare the time to completion against your previous single-agent review process. Expect 4-6x speedup on read-heavy reviews.

Frequently Asked Questions

Q: Do I need a separate API key for each subagent?

A: No — all subagents share the parent session's API key. Each subagent creates its own API conversation thread under the same key, so all tokens are billed to a single account.

Q: Can subagents access the parent session's file system?

A: Yes — subagents inherit the parent's working directory and file system access, subject to the tools configured in their TOML definition. An explorer agent limited to ["read", "grep", "glob", "search"] cannot edit files even if the parent session has write permissions.

Q: Is there a limit on how many subagents I can spawn?

A: Practically, yes — the max_threads setting caps concurrent subagents, and your API rate limit caps total throughput. OpenAI recommends 6-8 subagents on standard API tiers and up to 24 on Enterprise tiers. You can spawn more than max_threads in sequence as earlier subagents complete, but true parallelism is bounded by the thread pool.

Q: Does the parent session block while subagents run?

A: No — the parent session is non-blocking after spawning subagents. You can continue working in the parent session, spawning additional agents, or starting other tasks while subagents execute in the background. The await_all() call blocks until all spawned subagents complete.

Q: Can subagents spawn their own subagents?

A: Yes, if agents.max_depth is set to 2 or higher. The default is 1 (parent spawns subagents only), which prevents recursive agent trees. Setting max_depth = 2 allows a subagent to spawn helpers, but depth beyond 3 is not recommended due to coordination overhead.

Q: Are subagent results cached between sessions?

A: Not by default. Each subagent invocation creates a fresh agent process. You can implement caching at the workflow level by writing subagent results to disk and checking for existing results before spawning new agents, which is useful for expensive batch operations with stable inputs.

Q: Does Codex Subagents work with Codex's GUI mode?

A: Yes — the subagent system works in both terminal and GUI modes. The parent session's interface does not affect subagent execution. Subagent progress is visible in the parent session's activity log regardless of the interface mode.

Related Reading

INTERNAL-LINK: /blogs/codex-subagents-parallel-agents-guide-2026 — Complete guide to spawning parallel AI coding agents with Codex Subagents for PR review, batch analysis, and CI/CD integration.

INTERNAL-LINK: /workflows/laravel-breeze-vue-ssr-deployment-workflow-2026 — Deploying an AI-augmented development pipeline that uses Codex Subagents for automated code review and deployment verification.

INTERNAL-LINK: /blogs/v0-cursor-claude-code-ai-coding-tools-comparison-2026 — A comparison of AI coding tools including Codex Subagents for parallel agent orchestration versus single-agent workflows in Cursor and Claude Code.

INTERNAL-LINK: /blogs/ai-software-engineer-multi-agent-architectures-2026 — Multi-agent architectures for software engineering, covering Codex Subagents alongside other parallel agent frameworks.

INTERNAL-LINK: /workflows/github-mcp-server-setup-codex-2026 — Setting up MCP server integration with Codex for extended tool access in subagent workflows.

INTERNAL-LINK: /blogs/codex-agents-vs-cursor-tab-vs-windsurf-vs-copilot-2026 — Head-to-head comparison of Codex Subagents against other AI coding assistants for parallel task execution.

For official Codex Subagents documentation, visit https://openai.com/codex/subagents {rel="nofollow"}. The TOML agent specification reference is at https://openai.com/codex/docs/agents-toml {rel="nofollow"}. The Product Hunt launch page is at https://www.producthunt.com/products/codex-subagents {rel="nofollow"} with launch day benchmarks and community discussion. For API rate limit management, see the OpenAI documentation at https://platform.openai.com/docs/guides/rate-limits {rel="nofollow"}. The Codex CLI GitHub repository is at https://github.com/openai/codex-cli {rel="nofollow"}.