Codex subagents: parallel agents and custom agent files

Codex subagents are extra agents that Codex starts in parallel to handle part of a task, such as exploring code, running tests or reviewing one risk area, before it combines their results into one answer. You trigger them by asking ("spawn one agent per point"), and you can define your own custom agents as TOML files in .codex/agents/.

This guide covers when subagents help, how to start and manage them, the built-in agents, custom agent files and the [agents] settings. It is based on OpenAI's Codex subagents documentation, read on 24 October 2026.

What are Codex subagents?

OpenAI's docs use three terms:

• Subagent workflow: Codex runs parallel agents and combines their results.
• Subagent: a delegated agent Codex starts for one specific task.
• Agent thread: the thread where a subagent works. You can open it to see progress or results.

Current Codex releases enable subagent workflows by default, and subagent activity shows up in the ChatGPT desktop app, the Codex CLI and the IDE extension. ChatGPT Work on the web can also run subagents in its hosted environment, but custom agents are a feature of the local Codex clients.

Codex handles the orchestration: it spawns the agents, routes follow-up instructions, waits for results and closes threads. When several agents run, it waits until all the requested results are in, then returns one consolidated response.

When do subagents help?

The main benefit is a cleaner main thread. The docs describe two problems with long sessions: "context pollution", where useful information gets buried under noisy output, and "context rot", where performance drops as the chat fills with less relevant detail. Subagents move the noisy work, such as exploration notes, test logs and stack traces, off the main thread and send back summaries.

Good fits:

• Read-heavy work: codebase exploration, test runs, triage, log analysis and summarization.
• Independent checks: reviewing a branch for security, tests and maintainability at the same time.
• Large inputs: splitting analysis of a very large document into smaller pieces.

The docs advise more care with parallel write-heavy work, because several agents editing code at once can cause conflicts. OpenAI's own custom agent examples follow that shape: several read-only agents and one agent that makes the fix.

How do you start a subagent workflow?

Ask for it in plain words. Codex also delegates when applicable AGENTS.md or skill instructions request it. The docs say a good subagent prompt explains how to split the work, whether to wait for all agents, and what to return. Their example:

Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

Watching and steering them depends on where you work:

Everywhere, you can ask Codex in the chat to steer a running subagent, stop it, or close finished threads. In the CLI, an approval request can come from a thread you are not looking at; the overlay names the source thread, and pressing o opens it before you answer.

Which models do Codex subagents use?

If you set nothing, a subagent inherits the parent's model and reasoning effort. You can change that per task in your prompt, set defaults under [agents] in config.toml, or set model and model_reasoning_effort in a custom agent file.

OpenAI's guidance, as of October 2026:

• gpt-6.1-sol for demanding agents doing ambiguous, multi-step work, when your account or workspace has access.
• gpt-6-luna for fast, narrowly scoped agents doing clear, repeatable or high-volume work.

Higher reasoning effort improves quality on complex work but costs time and tokens. The docs suggest high for reviewer or security agents and low when the task is simple and speed matters. Model availability depends on your plan; see Codex pricing and OpenAI's models page.

How do you create custom agents in Codex?

Codex ships with three built-in agents:

• default: the general-purpose fallback.
• worker: focused on implementation and fixes.
• explorer: read-heavy codebase exploration.

To add your own, create one TOML file per agent in ~/.codex/agents/ (personal) or .codex/agents/ (project). Each file must define name, description and developer_instructions. This reviewer agent is copied from OpenAI's examples:

# .codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""

Then name it in a prompt: "Have reviewer find real risks in this branch."

Rules for custom agent files:

• The name field is the source of truth. Matching the filename to the name is just a convention.
• Your agent wins name clashes. A custom agent called explorer replaces the built-in one.
• Model keys allowed: model, model_reasoning_effort, model_reasoning_summary and model_verbosity.
• You can remove capabilities. Set features.shell_tool, features.apps, features.plugins, features.memories or features.request_permissions_tool to false. Turn off individual skills with [[skills.config]] entries, or bundled skills with skills.bundled.enabled = false.
• Some settings always come from the parent. sandbox_mode, approval_policy, model_provider and mcp_servers in an agent file do not override the parent. Configure MCP servers in the parent session so agents can use them.

The docs recommend agents that are "narrow and opinionated": one clear job, tools that match it, and instructions that stop it drifting into nearby work.

What goes in the [agents] config table?

Global subagent settings live under [agents] in config.toml. The Codex config guide covers where that file lives. The keys below are the documented ones; the values are examples to adjust, not defaults (OpenAI's own examples use 6 and 8 for the thread cap).

[agents]
enabled = true                               # false disables multi-agent tools
max_concurrent_threads_per_session = 6       # open spawned threads, excluding the main one
default_subagent_model = "gpt-6-luna"
default_subagent_reasoning_effort = "high"
interrupt_message = true                     # tell the agent when its turn is interrupted

When Codex picks settings for a subagent, an explicit value in the spawn request wins over the [agents] defaults, which win over the parent's values. A custom agent file that sets model or model_reasoning_effort takes precedence over all of these. If you leave max_concurrent_threads_per_session unset, Codex chooses the default; older configs can keep using max_threads.

What should you watch out for?

• Token cost. Every subagent does its own model and tool work, so subagent runs use more tokens than a single agent. Give light agents a faster model.
• Shared permissions. Subagents inherit the parent's sandbox and approval settings, including changes made with /permissions or --yolo. In the desktop app and IDE, pick the permission mode before you ask Codex to delegate. The approvals and sandbox guide explains the modes.
• Non-interactive runs. In codex exec or any run that cannot show a fresh approval, an action needing approval fails and the error goes back to the parent.
• Hooks see subagents. SubagentStart and SubagentStop hooks let you inject context or ask for another pass. Hook input uses the parent's session_id.

Claude Code has a similar feature with its own file format; the Claude Code subagents guide covers it, and skills vs subagents explains which to reach for.

Where do you keep the instructions your agents follow?

Agent files hold a role; skills hold the step-by-step method, and custom agents inherit skills from the parent. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own and installs every skill into Codex or Claude Code with npx skills add https://github.com/<you>/<repo>.git --all -g. To turn a review prompt into a skill, try the free SKILL.md generator.