Multi-Agent Workflows

Codex supports experimental multi-agent collaboration where you can run multiple specialized agents in parallel. Each agent has its own role, configuration, and context window, allowing you to parallelize complex tasks across your codebase.

Enabling Multi-Agent#

Add the feature flag to your ~/.codex/config.toml:

[features]
multi_agent = true

Defining Agent Roles#

Agent roles are defined in config.toml under the [agents] section. Each role gets a description and optionally a separate config file:

[agents]
max_threads = 6    # Max concurrent agents
max_depth = 1      # Prevent agents from spawning sub-agents

[agents.explorer]
description = "Read-only codebase explorer for gathering evidence before changes."
config_file = "agents/explorer.toml"

[agents.reviewer]
description = "PR reviewer focused on correctness, security, and missing tests."
config_file = "agents/reviewer.toml"

[agents.docs_researcher]
description = "Documentation specialist that uses the docs MCP server."
config_file = "agents/docs-researcher.toml"

Role Configuration Files#

Each role can override default settings. For example, agents/explorer.toml:

model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
You are a read-only codebase explorer. Your job is to gather evidence
and context. Never modify files. Report findings in structured markdown.
"""

Common Settings to Override Per Role#

| Setting | Use Case | |---------|----------| | model | Use a cheaper model for simple tasks | | model_reasoning_effort | Control reasoning depth | | sandbox_mode | Restrict write access for read-only roles | | developer_instructions | Give the role specific guidance | | approval_policy | Different approval levels per role |

How Orchestration Works#

1. Spawning — Codex automatically decides when to spawn agents, or you can ask explicitly: "Spawn a reviewer agent to check the auth module"
2. Parallel execution — Multiple agents run concurrently up to max_threads
3. Waiting — When agents are running, Codex waits for all results
4. Consolidated response — Results are merged into a single response

Thread Forking#

You can fork a conversation into sub-agents without leaving the current thread:

# In an active session:
"Fork an agent to review the database migration while I continue working on the API"

The /agent Slash Command#

Use /agent in the TUI to manage multi-agent workflows — enable agents, view active threads, and control handoffs.

Best Practices#

1. **One job per role** — An explorer should only explore, a reviewer should only review 2. **Match sandbox to role** — Read-only roles should use read-only sandboxes 3. **Use developer_instructions** — Give each role clear, specific guidance 4. **Start with max_depth = 1** — Prevent cascading agent spawns until you are comfortable 5. **Monitor with traces** — Codex records traces of every prompt, tool call, and handoff

Advanced: Agents SDK Integration#

For programmatic control, expose Codex CLI as an MCP server and orchestrate it with the OpenAI Agents SDK:

# Run Codex as an MCP server
codex mcp serve

This enables:

• Deterministic workflows with hand-offs and guardrails
• Full traces for every agent interaction
• Custom orchestration — Scale from single agent to full software delivery pipeline

Practical Example: Code Review Pipeline#

[agents]
max_threads = 4

[agents.security_reviewer]
description = "Reviews code for security vulnerabilities, injection attacks, and auth issues."
config_file = "agents/security.toml"

[agents.test_reviewer]
description = "Checks test coverage, identifies untested paths, suggests new tests."
config_file = "agents/tests.toml"

[agents.style_reviewer]
description = "Reviews code style, naming conventions, and documentation."
config_file = "agents/style.toml"

[agents.perf_reviewer]
description = "Identifies performance bottlenecks, N+1 queries, and memory leaks."
config_file = "agents/perf.toml"

This setup runs four specialized reviewers in parallel, each focused on a different aspect of code quality.

Next Steps#

• Configuration Reference — Full config.toml settings
• GitHub Integration — Automated PR workflows
• Non-Interactive Mode — Scripted multi-agent pipelines