Codex subagents are helper agents that Codex starts in parallel, each working on one piece of a job, and Codex then gathers their results into a single answer for you. You ask for them in plain words, such as "spawn two agents", and current Codex releases have the feature switched on by default.
The catch comes first, because it's the one people notice in their usage: OpenAI's docs say subagent workflows consume more tokens than a comparable single-agent run, because each subagent does its own model and tool work. More helpers means more usage. That's worth it for the right jobs and wasteful for the wrong ones, and the rest of this page is about telling them apart.
What a helper agent does
OpenAI describes a subagent workflow as one where Codex runs parallel agents and combines what they find. Each subagent works in its own agent thread, which you can open to check progress or results. It's the same idea as subagents in Claude Code, built into Codex and ChatGPT Work.
The docs say it's most helpful for work that splits cleanly, such as exploring a codebase or carrying out a multi-step feature plan. Their own example: Codex can break analysis of a multi-million-token document into smaller problems and return the distilled takeaways to the main thread.
You'll see subagents in the ChatGPT desktop app, which shows each thread; in the Codex CLI, where /subagents switches between threads; and in the IDE extension, where a background-agent panel above the composer shows status and lets you stop all active subagents. The web sidebar reports activity but gives you no controls to stop or steer one particular subagent. In ChatGPT Work, subagent activity is shown to eligible accounts, as of October 2026.
Why one long chat goes wrong
Big context windows still have limits. If the main chat, where you set requirements and make decisions, fills up with exploration notes, test logs, stack traces and command output, OpenAI says the session can become less reliable over time. It names two problems:
- Context pollution: the useful information gets buried under noisy working output.
- Context rot: performance drops as the chat fills with less relevant detail.
Subagents fix that by moving the noisy work off the main thread. The main agent keeps the requirements and decisions; the helpers do the digging and send back summaries, not raw logs. The docs suggest starting with read-heavy jobs like exploration, tests, triage and summarising, and being more careful with write-heavy jobs, because agents editing code at the same time can clash and add coordination overhead.
Asking Codex to split the work
At most intelligence levels you ask directly. The docs give phrasings like "spawn two agents", "delegate this work in parallel" and "use one agent per point". In ChatGPT Work, the Ultra level lets ChatGPT delegate on its own when parallel agents would help, but Ultra is only for eligible accounts and supported models, as of October 2026. Local Codex can also delegate when an AGENTS.md file or a skill's instructions ask it to.
A good request answers three questions: how to divide the work, whether to wait for every agent before carrying on, and what summary you want back. Here's OpenAI's three-angle review example, rewritten in my own words:
Copy this prompt
Review this branch using three subagents running at the same time. Give one the job of finding security risks, one the job of finding gaps in the tests, and one the job of judging how easy the code will be to maintain. Wait until all three have finished, then give me one summary grouped by those three categories, with the file names for each finding.
For a manager, that's the useful bit: one request, three independent reviews, one tidy report. Codex waits until every requested result is in, then returns a single consolidated response, so you don't have to read three transcripts unless something looks off.
The built-in agents, and making your own
Codex ships with three built-in agents, and you can add your own as small settings files:
| Agent | What it's for |
|---|---|
| default | General-purpose fallback when nothing more specific fits |
| worker | Execution: implementation and fixes |
| explorer | Read-heavy exploration of a codebase |
| A custom reviewer you define | Whatever you write into it, for example a narrow agent that looks only for correctness, security and test risks |
Custom agents are TOML files in an agents folder inside .codex, either in your home folder for personal agents or inside a project for project agents. Each file needs three things: a name, a description of when Codex should use it, and developer instructions. You can optionally set the model, reasoning effort, reasoning summary and verbosity. If you give a custom agent the same name as a built-in one, such as explorer, yours takes precedence. OpenAI's own advice is that the best custom agents are narrow and opinionated.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
Global settings sit under an agents section in your configuration: you can switch multi-agent tools off, cap how many spawned threads run at once, set a default model and reasoning effort for spawned agents, and choose whether an interruption gets recorded for the model to see.
The permissions they inherit
This is the rule I'd make sure everyone on the team understands. Subagents inherit the parent turn's sandbox and approval settings, including any changes made with /permissions or --yolo, and a custom agent file can't replace them. Custom instructions can ask an agent to avoid edits, but they don't create a separate read-only sandbox. Telling a reviewer agent not to change anything is a request, not a lock.
So choose the permission mode beneath the composer before you ask Codex to delegate. In the CLI, approval requests can pop up from a thread you aren't looking at; the overlay shows which thread it came from, and you can press o to open that thread before you answer. In non-interactive runs, anything that needs a fresh approval simply fails and the error goes back to the parent workflow.
Which model each helper should use
If you set nothing, a subagent uses the same model and reasoning effort as the parent. The docs suggest gpt-6.1-sol for demanding agents doing ambiguous, multi-step work, and gpt-6-luna for fast, narrowly scoped, high-volume jobs. Reasoning effort works the same way: low when the task is simple and speed matters most, high when an agent has to trace complex logic, such as a reviewer or security agent. Higher effort means slower answers and more tokens, so don't set every helper to the top level by habit.
My verdict: I'd use subagents for reading and reviewing, and skip them for edits until your approvals are tight. Try the three-way review above on one branch, see whether the summary saves you time, then decide where else it earns its keep. If you're new to Codex altogether, start with my beginner walkthrough first.
If you'd like help deciding which jobs to hand to a team of AI agents and which to keep human, that's the kind of AI enablement I help with. I run AI training and workshops for teams, and help businesses with AI enablement and workflow automation, so the busywork runs itself and people get time back. Most of that work is with SaaS marketing teams and small businesses. Here's how we can work together.
Frequently asked questions
What are subagents in Codex?
They're helper agents Codex starts in parallel to handle separate parts of a task. Codex waits for their results and combines them into one response.
Do Codex subagents use more tokens?
Yes. They consume more tokens than a comparable single-agent run, because each subagent does its own model and tool work.
How do I turn on subagents in Codex?
Current Codex releases enable subagent workflows by default. Ask for them directly, for example by telling Codex to spawn two agents or use one agent per point.
Can a subagent have different permissions from the main chat?
No. Subagents inherit the parent turn's sandbox and approval settings, and a custom agent file can't override them.
What are the built-in Codex agents?
Codex ships with default, a general-purpose fallback; worker, for implementation and fixes; and explorer, for read-heavy codebase exploration.
