Subagent Support

Subagent feature related PRs are going on. Check them and please feel free to share if there is anything that should be considered: https://github.com/openai/codex/pulls?q=is%3Apr+subagent+is%3Aopen

I'm currently working on this issue in #3655.

FYI for anyone who wants a workaround while waiting for the above PR to get released, the following prompt works well for me

You are running inside the Codex CLI and need to orchestrate additional headless Codex instances (“subagents”) to tackle work individually or in parallel. Keep these lessons in mind:

  1. Launch subagents with `codex --yolo exec "your prompt"`; always quote/escape anything that the shell might interpolate (avoid unescaped backticks or `$()`).
  2. When spawning subagents via a shell tool call, override the wrapper timeout so each run can last up to 30 minutes, e.g. `timeout_ms: 1800000`.
  3. Parallel runs can be started with background jobs (`& … & wait`), but the wrapper may still report exit code 124 if the combined command exceeds the timeout; inspect each subagent’s log to confirm whether it completed.
  4. Subagent sessions inherit CLI defaults (e.g., approval policy, sandbox mode may still show as read-only), so plan prompts accordingly and keep them lightweight when possible.

@seratch according to the repo contribution guidelines, here is an issue that describes a desired feature, you commented before asking for input on PRs that should be considered.

@cognitive-glitch has references a PR on the topic. I suggest it should be considered.

Please give official input from the organization on the direction here.

when?

This is much needed.

+1

+1

want

much need

Need this for sure to preserve context

+1

Yes please, Would love to see this as well

+1

+1

I have created similar to sub-agent CEO->Manager->Worker

does the manager organizes daily standups for the agent workers?

(_sorry, couldn't resists :homer:_)

+1

+1

+1

+1

I use Goose for it. They have a concept of recipes basically subagents. each is stored separately so you can always run it for mundane tasks such as review PR etc. I am still surprised such a useful feature is not present is most coding tools

Is there any progress on this? Are there viable and production-ready alternative implementations? I've checked Goose, and it looks interesting. But I'd really like to have my own subagents collection native in Codex...

+1

Something is happening here: https://github.com/openai/codex/pull/7526

Is there any progress on this? Are there viable and production-ready alternative implementations? I've checked Goose, and it looks interesting. But I'd really like to have my own subagents collection native in Codex...

None! Roo has something resembling it but it is very rudimentary. It would be nice to have a collection of predefined agents and have an ability to pick your "team" and let your "pm" or "lead dev" coordinate/manage the task. I can think of nice UI as well where you'd see who's done and what showing it as somekinf of timeline of task execution

Hi all,

Good to see so much enthusiasm about subagents. I would like to get a sense of what exactly would you want as "subagent" is a broad term that is used to mean quite different things.

Could you describe in a couple of sentences or small mockups HOW would like to see those agents coming in Codex? And perhaps even more importantly, which problems you are hoping to solve with this.

We will consider them and work on a design to bring this to codex core.

@jif-oai

To me, this is about having different agents that specialize in different domains and can tackle tasks on the same project in different ways, without needing to share the entire context.

For example, you could have a “backend agent” and a “frontend agent” that communicate with each other. The frontend agent might ask the backend agent about an endpoint definition without needing to know the underlying implementation or validation rules.

Similarly, you could have a “security agent,” a “design agent,” and a “developer agent,” each with their own specialization, reviewing one another’s work so that all of them approve the final result.

Dividing responsibilities reduces the cognitive load for each agent, making them more effective. This modular architecture also lets you swap in improved agents (e.g., “designer agent v2”) without disrupting the others, which is harder in a monolithic system.

I hope I explained my vision well.

Basic idea is to be able to setup an orchestrator agent that provides several subagents with very task specific context, so we can perform complex tasks far surpassing one context window.

Orchestrator -> Gives X number of subagents the correct input data. Each subagent has it's own specific instruction on what action to perform -> Returns results to orchestrator that summarizes what's been done or centralizes outputs (if needed)

It is possible to do this as a human but requires alot of prompting.

+1 to the above.

for me, it's long-lived orchestrators that can stay alive across extended sessions without accumulating unnecessary context.

the orchestrator should be able to spawn task-scoped subagents with isolated context, execute them independently, and receive structured results back without polluting the main agent’s long-running state.

would also be great if we could make the return surface configurable, e.g. return:

• final output only
• key intermediate artifacts
• full trace / reasoning

+1 to previous comments.

subagents are not for roleplaying, they're for saving the orchestrator's context window.

orchestrator thread spawns self-contained subtasks as part of a bigger implementation. for each subtask (with its own context window), they do discovery, read tens or hundreds of source files, make decisions, implement, test, then return with 'success' to the orchestrator so the orchestrator can continue the main thread.

this saves hundreds of thousands of tokens from the main orchestrator thread, and avoids getting into the 'dumb zone' (the end of context window).

with competing tools, I'm bound to dumber models, but I can use subagents and I have 12h+ threads running implementing a big epic feature. with codex-cli, I have the best model, but can't orchestrate such a complex task due to the lack of features on codex-cli.

I would like to have a main Orchestrator agent able to automatically spawn subagents.

The main pain point of using Codex for me currently is constantly resetting chats after context window utilization gets large and agent`s performance deteriorates. At the end of each such session I always have to provide repeatable instructions like make sure codebase is consistent, documents are up-to-date, update agent hand-off document etc. And then when I start a new agent, I have to provide standard agent onboarding instructions like read these documents, familiarize yourself with codebease by running these scripts etc. And on top of all of that, I have to constantly monitor context window utilization to know when to restart.

So doing all of the above, I basically serve as a "human orchestrator". Orchestrator/subagents pattern will simplify all of the above and save me a lot of manual work.

Being able to define multiple subagent types/models/instructions like e.g., in Roo/Kilo Code may be useful too, but is not critical.

@jif-oai

Subagents should be implemented in a way that enables codex-cli to receive incremental updates that will eventually allow it to launch dynamically generated subagents. Dynamically generated subagents have dynamically generated strategies.

It's based on a technique called Experience-Guided Reasoner (EGUR), described in the recent paper "Experience-Guided Adaptation of Inference-Time Reasoning Strategies" (https://arxiv.org/abs/2511.11519). It is similar to Poetiq's (https://x.com/poetiq_ai/status/2003546910427361402):

We finally had a moment to run our system with GPT-5.2 X-High on ARC-AGI-2! Using the same Poetiq harness as before, we saw results as high as 75% at under $8 / problem using GPT-5.2 X-High on the full PUBLIC-EVAL dataset. This beats the previous SOTA by ~15 percentage points.

Instead of using a fixed, statically defined, set of subagents (e.g., "Reviewer", "Tester"), the system should be able to have a "Guide" meta-agent that writes the code for temporary subagents on the fly, optimized for the user's current request. The system should be able to generate a complete execution plan (the subagent) based on previous history.

1. Guide (Meta-Agent): Receives the user query (e.g., "Refactor this function") and retrieves relevant past experiences from memory.
2. Strategy Generation: The Guide outputs the code for a specific subagent strategy.

• Example 1 (Complex Task): If I ask for a refactor, it might generate a subagent that runs a loop: [Read Code -> Write Tests -> Modify Code -> Run Tests -> Fix Errors].
• Example 2 (Simple Task): If I ask to fix a typo, it generates a cheaper pipeline: [Read File -> Regex Replace -> Save].

1. Execution: This generated subagent executes.
2. Consolidator (Feedback Loop): After execution, the system analyzes the trace (cost, success/failure). If this specific strategy worked well, it saves it to a "Strategy Library". During the task it is able to use this successful subagent logic again.

"Pseudocode"

# The Core "Manager" Logic
def handle_user_query(query, memory):
    # 1. THE GUIDE: Decides what kind of subagent is needed
    # It generates a 'strategy' string (code) based on what worked previously
    subagent_strategy_code = GuideModel.generate(
        prompt="Create a strategy to solve: " + query,
        context=memory.get_relevant_experiences(query)
    )
    
    # subagent_strategy_code might be a recursive agent for hard tasks
    # or a linear script for simple ones.
    
    # 2. COMPILE & EXECUTE
    subagent_executable = compile_strategy(subagent_strategy_code)
    result, trace = subagent_executable.run(query)
    
    # 3. THE CONSOLIDATOR: Learn from the result
    # If this generated subagent failed or was too expensive, remember that.
    memory.update(query, trace, result.success)
    
    return result

Advantages

1. "Overthinking" vs. "Underthinking" Trade-off: Static agents often use too many tokens for simple tasks (overthinking) or fail to loop sufficiently for hard tasks (underthinking). By generating the subagent at inference time, codex-cli can deploy a heavyweight recursive agent or a lightweight script, optimizing both cost and latency.
2. Adaptability: A fixed "QA Subagent" might not fit my specific testing framework. With EGUR, if I correct the agent's testing approach once, the Consolidator updates the memory. The next time the Guide creates a subagent, it includes my specific testing preferences in the strategy logic itself.
3. Continual Learning: The system builds a library of effective strategies over time. It effectively "learns to code", caching successful workflows for specific types of features or bugs in my repository.

TL, DR:

instead of fixed agents, give us a workflow that is able to perform "strategy engineering" at inference time.

Subagents can be used in countless ways. The important part is that they run in the background with their own context windows.

Very simply put, the parent agents provides the subagent some prompt (based off it's own context and the subagent's instructions in the MD file), and the subagents then go off and do work, and return only their final output to the parent agent, thus saving the parent all that context window usage.

The prompt and instructions for handoffs can be customized via the subagent prompt instructions.

No need to overcomplicate. That's really the crux imo. @jif-oai

Agreed with many of the comments above and generally think subagents are a big unlock.

As another commenter said, it's more about context management than hard-coding roles where skills would be a better fit.

That said, having worked with other systems that have subagents, there is a significant risk of performance issues for most users if context drift isn't handled properly and natively (which is a hard problem).

E.g. if you simply pass summaries from subagents back to orchestrator/main agent, you'll eventually converge on the average of your goals.

The handoff only works well when each subagent knows exactly what is important to return and with what degree of detail/nuance.

The adaptive subagent generation sounds like an interesting approach that could help with drift. But I also think there's room for canonical agents that own their domain, and are packed with domain-relevant skills.

The topic of roles such as orchestration, architect, debug, coding, etc. is nothing new. But I have to say that my experience with typical VS Code IDE tools has been really bad. However, these alternative coding agents also used XML structures instead of native function calling and did not yet use the ResponseAPI with better caching.

In contrast, the simple Codex CLI has been very effective, precise, and neat since 0.2. This advantage should not be lost with Subagent initiatives. Otherwise, I see many advantages to it when implemented correctly. But sometimes, keeping it simple and stupid is not entirely wrong when it comes to finding the right path.

One of the biggest complains with Codex Xhigh is that its too slow, which can be improved by using sub agents and ofc the other benefits like keeping context clean but I see your point as well @wbdb

Its a clash of philosophies at this point, but claude code is doing such a good job with subagents, I imagine it would be a net positive.

Edit: This is again only for reading code and not actually editing that said code, I would be terrified of a sub agent that can edit code without my inputs or work without my supervision , the slop would be crazy but using a sub agent like 5.2 med would speed up the flow so much @jif-oai

@kanlanc Take a look here https://x.com/thsottiaux/status/2005433644803137818

+1

codex-subagent-plugin
I tried creating a plugin that combines CLI tools and skills to achieve this, and it worked quite well.

I need this. C'mon Claude is ahead atm.

Subagents are already being worked on and in fact an early form of them are already in the alphas. You can safely close this now. Should come soon. Cheers.

@am-will, we'll leave the issue open until it's ready for use.

i can't wait! so exciting.

Can someone help me navigate to an active PR for this ? thank you

@ykaranke-allata, there's not a single PR. It's being implemented in stages — a long series of PRs.

I got forced to use Claude Code for repo based knowledge work orchestration workflows because Codex sadly does not support subagents & .prose is not usable due to it https://www.prose.md/learn

I decided to use this: https://github.com/just-every/code -It's a codex fork with the kitchen sink

every code is truly fan-freaking-tastic. but i'm excited for when codex makes it native. i'm pretty sure they have some tricks up their sleeves that make it unique.

Hey yall, while we wait on the official port, I created a subagent skill that will call itself when it determines that a context-heavy task is going to use a lot of your context window.

Codex Subagent Skill can be found in here: https://github.com/am-will/codex-skills

Read about it here: https://x.com/LLMJunky/status/2013002697654284582?s=20

Enjoy! It works great.

Also uses Codex 5.1 Mini for exploratory non-reasoning level tasks to save usage.

Note: turn on background shell in Codex for this to work properly: type /experimental in Codex CLI

Just a hint for all others who are also waiting. Three current options I found:

1. Create a skill where you guide codex to use codex exec "subagent prompt". if you need custom permissions and stuff, create different profiles in settings.toml and use via --profile key

1. Use codex mcp command to serve codex in MCP mode and connect it to normal codex instance (aka main agent)

1. Just use OpenCode with new official integration of openai subscription. So, best gpt-5.2 models within the tool with native agents

You can enable Multi-Agents experimental option and ask codex to use subagents

ive been using subagents extensively all week, and while they really need some specific steering to get the most out of them, they are indeed a huge unlock.

i had swarms producing incredible one shots after I figured out how to use them optimally.

well done OpenAI. Needs some polish but very close.

I recommend putting this in your AGENTS.md

Subagents
ALWAYS wait for all subagents to complete before yielding.
Spawn subagents automatically when:
Parallelizable work (e.g., install + verify, npm test + typecheck, multiple tasks from plan)
Long‑running or blocking tasks where a worker can run independently.
Isolation for risky changes or checks

Subagents ALWAYS wait for all subagents to complete before yielding.

This is crucial.

Once I enabled collab, I found that the subagents yielded immediately while the main agent remained stationary and didn’t resume work.

So what we need may be a kind of parallel explorers and context container, filter.

Whether subagent is not so much important, pack it as api / mcp / simple command is ok, just handling asynchronous waits and obtaining the final, efficient information is sufficient.

I wouldn't favor parallel execution of edit operations to avoid consistency issues. Delete and edit actions are fast when sufficient context information is available. The biggest drawback is the sequential, iterative exploration of the context. We can mitigate this by using agents.md constraints and guiding subagents (simultaneously alleviating the limited context problem through independent context containers and filters) to improve behavior.

understanding correctly?

Just to add my $0.02 (or really, a lot more), I'm looking to move some large portion of my several thousand bucks a month of claude code usage over to codex... the better instruction following of codex models is extremely attractive. But it's hard for me to justify it until I can have the benefits of subagents for proper context management!

Given the huge expenditures of the highest-using-users of agentic LLMs like codex CLI and claude code, it always blows my mind when the companies that build them fall behind... presumably you guys don't constantly run up against the same costly rate limits that I do! 😉😉😉🤣🤣🤣

I wrote an article on how to get the most out of subagents on Codex.

Its sometimes quirky but extremely powerful. Hope you get something of value from it.

https://x.com/i/status/2014521564864110669

I've created a PR to show how subagent delegation could work in a fully event driven way which doesn't require inoking wait and blocking the main agent https://github.com/mikekelly/codex/pull/1

Codex v0.89.0

<img width="1047" height="185" alt="Image" src="https://github.com/user-attachments/assets/df715079-d662-49a8-b216-b99471f90312" />

@TylonHH The option seems to be missing again in 0.91 for both Windows and WSL2?

<img width="1025" height="171" alt="Image" src="https://github.com/user-attachments/assets/4e29f6b6-bf01-4fbc-acc3-4ae5420efc79" />

The feature is still under development. It's not yet at the "experimental" phase. We got a little ahead of ourselves in adding it to the experimental menu, and a number of users who tried it ran into a bug that quickly drained their weekly usage allowance. We'll add it back to the experimental menu once it is ready.

Following up on @jif-oai’s request for “how should subagents show up in Codex” mockups/UX: I filed a feature request for the main collab TUI gap I hit: persistent multi-agent situational awareness once you’ve entered a thread.

New issue: openai/codex#9902

In short: I suggest to add an optional left “Agents” sidepanel (toggleable; or auto-enabled when >1 agent exists) that stays visible in the main chat view and shows:

• active agent/thread list with status + last-activity timestamp
• one-line preview per agent (last summary preferred, else last output)
• badges for approvals pending / tool-user-input pending / error / archived
• quick actions: jump to agent thread, queue follow-up without interrupting, interrupt+enqueue, close/dismiss

This complements subagent support by reducing context switching back to the picker and scaling better as agent count grows (especially when approvals/tool requests arrive on other threads).

I get tired of switching between terminal tabs and copy pasting output, when it could just be managed by a main orchestrator agent.

@etraut-openai @jif-oai:

I strongly recommend moving away from wait or polling, and towards fully event-driven async ("fire and forget") subagents. Under this model the main agent simply fires off subagents and yields back control to the user, allowing the user to continue chatting with the main agent and kick off more agents if needed. When subagents complete or error, the harness notifies the user and "wakes up" the agent by sending a user message with the subagent completion event (including the final assistant message of the subagent as a 'result'). This makes more efficient use of context than having the agent poll, and it allows the main agent to collaborate with the human on orchestration and additional parallel work.

I spiked out an implementation here which shows how it can work (the system prompts need to better frame the flow to the agent so it more consistently fires, forgets, and yields back to the user. But it hopefully gives an idea of what this flow could look like.

https://github.com/mikekelly/codex/pull/1

@etraut-openai @jif-oai: I strongly recommend moving away from wait or polling, and towards fully event-driven async ("fire and forget") subagents. Under this model the main agent simply fires off subagents and yields back control to the user, allowing the user to continue chatting with the main agent and kick off more agents if needed. When subagents complete or error, the harness notifies the user and "wakes up" the agent by sending a user message with the subagent completion event (including the final assistant message of the subagent as a 'result'). This makes more efficient use of context than having the agent poll, and it allows the main agent to collaborate with the human on orchestration and additional parallel work. I spiked out an implementation here which shows how it can work (the system prompts need to better frame the flow to the agent so it more consistently fires, forgets, and yields back to the user. But it hopefully gives an idea of what this flow could look like. mikekelly#1

I like this but I do find it annoying sometimes in Claude because the agent fails to wake up. Often, I have no idea if it ever completes successfully. It got so annoying I started explicitly asking the parent to run subagents in the foreground so i could monitor progress. Just something to look out for.

Also, can you please put down the hammer? You're making the guests nervous.

> @etraut-openai @jif-oai: > I strongly recommend moving away from wait or polling, and towards fully event-driven async ("fire and forget") subagents. Under this model the main agent simply fires off subagents and yields back control to the user, allowing the user to continue chatting with the main agent and kick off more agents if needed. When subagents complete or error, the harness notifies the user and "wakes up" the agent by sending a user message with the subagent completion event (including the final assistant message of the subagent as a 'result'). This makes more efficient use of context than having the agent poll, and it allows the main agent to collaborate with the human on orchestration and additional parallel work. > I spiked out an implementation here which shows how it can work (the system prompts need to better frame the flow to the agent so it more consistently fires, forgets, and yields back to the user. But it hopefully gives an idea of what this flow could look like. > mikekelly#1 I like this but I do find it annoying sometimes in Claude because the agent fails to wake up. Often, I have no idea if it ever completes successfully. It got so annoying I started explicitly asking the parent to run subagents in the foreground so i could monitor progress. Just something to look out for. Also, can you please put down the hammer? You're making the guests nervous.

Sorry I'm inseparable from the hammer!

I think the problem you mentioned is more about ensuring that the TUI has strong affordances for tracking the progress of backgrounded agents while they're in flight. I built my own TUI for this for claude's background agents (that shows a list of live and completed agents, and follows the activity stream of a live agent). I suggest something like this be integrated as a first class component of the codex UI, to avoid the lack of visibility you're describing which CC suffers from.

Just wanted to drop a note on a current issue I stumbled across. Seems the agent needs to have agent ids in order to close them. There's no tool for listing them. Usually the AI holds the ids in it's context window just fine. If you hit compaction while 6 agent sessions are running though you will be:

• Unable to start new agent sessions (because you're capped at 6)
• Unable to close existing sessions (because it doesn't know the ids)

under development

I have a bit of a silly request - can you label subagent related PRs with a github label saying they're related to the subagents feature? Just for us interested in following along!

(n.b. it's also great for organizing tasks for easy agentic orchestration)

Could a subagent use medium reasoning effort while a main agent uses xhigh reasoning effort?

Since subagents now is a feature of claude, opencode , cagent - not having them in codex is not nice thing. Would be great to have subagents implemented too

Since subagents now is a feature of claude, opencode , cagent - not having them in codex is not nice thing. Would be great to have subagents implemented too

You can enable them, in you add this to ~/.codex/config.toml

collab = true

@ThePlenkov, we recently added subagent support as an experimental feature. If you'd like to try it, you can enable it with the /experimental slash command in the CLI. Or manually edit the config.toml file as @enriquemorenotent mentioned above.

@etraut-openai amazing! Could you please may be share some md document explaining how to use them in codex? thanks!

@ThePlenkov, we don't have documentation for the feature yet. (Sorry, but we've been really busy with the launch of the new Codex app over the past week.) Other Codex community members have been playing with the subagents feature and may be able to offer some tips and insights. Please give it a try and let us know if you run into any problems or discover some interesting use cases for it.

Could a subagent use medium reasoning effort while a main agent uses xhigh reasoning effort?

They dont have this yet. The subagent current inherits the parent agent's reasoning level except for when a subagent is autonomously called to do file repo exploration (as per the source code last time I checked).

I agree, nice feature. Would love to see it.

@etraut-openai amazing! Could you please may be share some md document explaining how to use them in codex? thanks!

I did an early guide here: https://x.com/LLMJunky/status/2014521564864110669

I launched subagent swarm skills here: https://x.com/LLMJunky/status/2019164903827992810?s=20

You have to enable collab = true in config.toml, they removed it from /experimental menu 3-4 updates ago.

I recommend putting this in your global AGENTS file

## Subagents
- ALWAYS wait for all subagents to complete before yielding.
- Spawn subagents automatically when:
  - Parallelizable work (e.g., install + verify, npm test + typecheck, multiple tasks from plan)
  - Long‑running or blocking tasks where a worker can run independently.
  - Isolation for risky changes or checks

@am-will Perhaps an optimized variant so that tasks that are dependent on each other are not parallelized.

## Subagents
- ALWAYS wait for all subagents to complete before yielding.
- Spawn subagents automatically when work is **independent and parallelizable**:
  - Multiple tasks from the plan that do not share state/files heavily
  - Long-running or blocking steps a worker can run alone (build, tests, scans)
  - Isolation for risky changes or checks

- Do NOT spawn subagents when work is **tightly coupled**:
  - Task B depends on code/decisions/artifacts from Task A (sequential handoff needed)
  - Tasks require frequent coordination in the same files or a single coherent design

- Rule of thumb:
  - Use subagents only if dependencies are minimal or can be handled via a clear contract (inputs/outputs, interfaces). Otherwise keep it in one agent.

@etraut-openai
Can we see in the Codex CLI when it uses subagents? Is it sufficient to activate the experimental feature so that it is used properly (internal prompt or something similar), or is such an instruction in AGENTS.md very helpful?

> @etraut-openai amazing! Could you please may be share some md document explaining how to use them in codex? thanks! I did an early guide here: https://x.com/LLMJunky/status/2014521564864110669 I launched subagent swarm skills here: https://x.com/LLMJunky/status/2019164903827992810?s=20 You have to enable collab = true in config.toml, they removed it from /experimental menu 3-4 updates ago. I recommend putting this in your global AGENTS file `` ## Subagents - ALWAYS wait for all subagents to complete before yielding. - Spawn subagents automatically when: - Parallelizable work (e.g., install + verify, npm test + typecheck, multiple tasks from plan) - Long‑running or blocking tasks where a worker can run independently. - Isolation for risky changes or checks ``

Having used subagents extensively in other harnesses for a while now, my experience is that you get a much better UX if you NEVER wait for subagents before yielding back to the user. It puts the human back in the loop as much as possible - allowing them to initiate other parallel work, collaborate with the main agent on orchestration, discuss changes of plans based on individual subagent feedback, etc. Frontier models are now more than capable of dealing with that flow.

## Orchestrator and Subagents

- The main agent owns planning, task breakdown, and final integration.
- The main agent must dispatch subagents for any work that can run in parallel without shared state or sequencing.
- There is no fixed cap on parallel subagents when it improves throughput.
- Subagents must only perform their assigned task. They must not expand scope or initiate extra workflows.
- Subagents must not ask the user questions. If blocked, they must ask the main agent and wait for explicit direction.
- The main agent must wait for all subagents and reviews before the final response.

I used this for two weeks and it was really good.

Subagents will be extremely slow if they ask questions about unclear tasks in the thread.

---

This allows for more agents. The hardcoded limit of six is too low. I understand the team changed it from eight to six due to a previous usage issue report.

> @etraut-openai amazing! Could you please may be share some md document explaining how to use them in codex? thanks! I did an early guide here: https://x.com/LLMJunky/status/2014521564864110669 I launched subagent swarm skills here: https://x.com/LLMJunky/status/2019164903827992810?s=20

One of the coolest things about this era is how many of us are converging on similar solutions all independently

One of the coolest things about this era is how many of us are converging on similar solutions all independently

If you really believe that everyone has developed this for themselves and had no support from an AI, then this is really a blatant coincidence.

> > @etraut-openai amazing! Could you please may be share some md document explaining how to use them in codex? thanks! > > > I did an early guide here: https://x.com/LLMJunky/status/2014521564864110669 > I launched subagent swarm skills here: https://x.com/LLMJunky/status/2019164903827992810?s=20 > You have to enable collab = true in config.toml, they removed it from /experimental menu 3-4 updates ago. > I recommend putting this in your global AGENTS file > `` > ## Subagents > - ALWAYS wait for all subagents to complete before yielding. > - Spawn subagents automatically when: > - Parallelizable work (e.g., install + verify, npm test + typecheck, multiple tasks from plan) > - Long‑running or blocking tasks where a worker can run independently. > - Isolation for risky changes or checks > `` Having used subagents extensively in other harnesses for a while now, my experience is that you get a much better UX if you NEVER wait for subagents before yielding back to the user. It puts the human back in the loop as much as possible - allowing them to initiate other parallel work, collaborate with the main agent on orchestration, discuss changes of plans based on individual subagent feedback, etc. Frontier models are now more than capable of dealing with that flow.

the issue with this is they never get back to you or check on the work in the background. They say they will, but dont, so both you and the orchestration layer are both left guessing as to whether the work was finished. This is a widespread issue reported by many people (incl some here in this thread!)

I dont see how that is helpful. Had it happen to me dozens of times. If it did actually get back to you, then I might agree. The way Claude manages this, at present, is much better because it clearly states on screen how many background sessions there are, and it "wakes" the agent back up even after yielding to provide updates to the orchestration layer.

Also, I don't need to be in the loop because I spend a lot of time in planning. The orchestration layer is VERY good at detecting and fixing problems. I would encourage you to try a bit more of a hands off approach and see how far you can push it. You might be surprised!

@am-will Perhaps an optimized variant so that tasks that are dependent on each other are not parallelized. `` ## Subagents - ALWAYS wait for all subagents to complete before yielding. - Spawn subagents automatically when work is **independent and parallelizable**: - Multiple tasks from the plan that do not share state/files heavily - Long-running or blocking steps a worker can run alone (build, tests, scans) - Isolation for risky changes or checks - Do NOT spawn subagents when work is **tightly coupled**: - Task B depends on code/decisions/artifacts from Task A (sequential handoff needed) - Tasks require frequent coordination in the same files or a single coherent design - Rule of thumb: - Use subagents only if dependencies are minimal or can be handled via a clear contract (inputs/outputs, interfaces). Otherwise keep it in one agent. `` @etraut-openai Can we see in the Codex CLI when it uses subagents? Is it sufficient to activate the experimental feature so that it is used properly (internal prompt or something similar), or is such an instruction in AGENTS.md very helpful?

I like this, though I actually do this separately, but still a good call.

You can see how I handle parallelization here: https://github.com/am-will/swarms

I it through prompting in planning to create a dependency map direclty in the plan, and then I call a parallel-task skill which basically calls n number of subagents in waves based on the number of unblocked tasks. Your "tightly coupled" tasks as you call them (I like that language!) are segemented so that if one depends on another, or edits the same file, they are not launched at the same time.

Once the subagent is done with its work, it does three things:

• Runs tests (if applicable)
• Updates the plan with state & a log of its work
• Provides update to the orchestrator, incl any errors, blockers, or gotchas

The orchestrator then:

• Makes sure it updated the plan
• Verifies the subagent(s) did their work correctly
• Either asks subagent to fix, or notes the problem and fixes later.

The result is kinda magic. It works incredibly well. Kinda proud because to TylonHH's point, Github released more or less the same thing the day after I did lol. Except they use a bit of a more sophisticated SQLite DB to manage tasks/state.

At the end of the day, many people are going to come up with the same solution, not because AI is helping, but because we're all running into similar bottlenecks and issues. I have been parallelizing my work like this for quite some time, but instead of subagents, I would launch numerous terminal sessions at once. Back then, my "parallel-task" skill was a slash command and functioned exactly the same way: checked the plan, found unblocked task, did task, update plan. And I would just launch as many sessions as needed.

But subagents unlock an entirely new layer and capability because it is managing the higher level details at all times, and correcting any mistakes in realtime. Even with the dependency graph, they will still make some mistakes, but I have found that I can be entirely hands off during implementation provided that I spend a great deal of time making sure the plan is well written and correct. Read the plan. Push back. Iterate. If you don't know something, look it up or ask the agent.

While I am a power user of coding agents, I take much inspiration from people who are true industry leading experts, I ask them a ton of questions, and all of them are working this way in one form or another. Either by subagent or numerous parallel terminals. And the point isnt that you also need to launch everythign in parallel. In fact you definitely dont, but rather, that if you provide really strong upfront guidance and a way for your agent to validate its work, you can really just let it work.

What an amazing time to be alive.

If you really believe that everyone has developed this for themselves and had no support from an AI, then this is really a blatant coincidence.

8 months ago I had to really fight most of these LLMs to do this stuff and really, any meta-prompting. The idea is obvious, but everyone wants to throw complicated ideas at the problem. As I've had to do progressively less and less handholding, I've been able to apply progressively more and more complex orchestration patterns. You can pick which parts of it any one of us are individually responsible for as opposed to codex, or Claude code, but then again, I'd wonder why you're using these tools at all.

It's a new era of standing on the shoulders of giants, and that's a beautiful thing, not a tragedy ✨

Do subagents use the main agent's handle/connection to access MCP tools/servers ?

@etraut-openai

Eric, you previously came to the rescue on symlink support to allow Claude Code skills into Codex — thanks again.

Subagent support is still missing in Codex, and this issue is exactly the gap:

1. Skills/config define what to do, but not who does it (model, tools, permissions, prompt, memory).
2. Claude Code’s per-agent YAML gives a portable, version-controlled way to define that who.
3. Without Codex subagents, teams end up maintaining two parallel systems and lose portability.

Proposed ideal (aligned with this issue):

1. A first-class agent registry in Codex (project + user scope).
2. Agent definition files compatible with Claude Code’s format (or a small, documented superset).
3. Ability to invoke agents directly or pair with skills (e.g., a skill that routes to a named agent).
4. Model/tools/permissions/memory/prompt all captured per agent, and checked in at the project level.

Can you give a sense for your alignment with this proposed ideal and where on the roadmap it might fall?

Do subagents use the main agent's handle/connection to access MCP tools/servers ?

Subagents have access to everything the parent does. Mcp, skills, and model/reasoning level.

edit: model/reasoning can't be changed even for file exploration, even though it was in the repo. as far as I can tell, that tool doesn't exist.

@etraut-openai Eric, you previously came to the rescue on symlink support to allow Claude Code skills into Codex — thanks again. Subagent support is still missing in Codex, and this issue is exactly the gap: 1. Skills/config define what to do, but not who does it (model, tools, permissions, prompt, memory). 2. Claude Code’s per-agent YAML gives a portable, version-controlled way to define that who. 3. Without Codex subagents, teams end up maintaining two parallel systems and lose portability. Proposed ideal (aligned with this issue): 1. A first-class agent registry in Codex (project + user scope). 2. Agent definition files compatible with Claude Code’s format (or a small, documented superset). 3. Ability to invoke agents directly or pair with skills (e.g., a skill that routes to a named agent). 4. Model/tools/permissions/memory/prompt all captured per agent, and checked in at the project level. Can you give a sense for your alignment with this proposed ideal and where on the roadmap it might fall?

Sorry to interject. Seconding this, would love to be able to have customizable agent definitions, mostly because I want more configurability on the model/reasoning level.

Ability to invoke agents directly or pair with skills (e.g., a skill that routes to a named agent).

In the meantime... you can invoke agents directly within skills already. While they will inherit the parent agent's model/reasoning, you can still invoke them easily. Either directly, or you can just create a skill and name the definitions there. If you're trying to create a specific role subagent, you just invoke the "$xyz-agent" and you more or less give it the same instructions you would a Claude subagent.

"Call a subagent with the following role: "you are a specialized....xyz" and it will automatically pass the prompt plus any other context you give it. This more or less solves 3 of the 4 ideals you suggested. But it is missing, imo, the most important one (model configurability). Not quite what you're asking for, but pretty close. I use this all the time, and it works well. Hope it helps you.

Hope they add YAML support soon.

> Do subagents use the main agent's handle/connection to access MCP tools/servers ? Subagents have access to everything the parent does. Mcp, skills, and model/reasoning level. edit: model/reasoning can't be changed even for file exploration, even though it was in the repo. as far as I can tell, that tool doesn't exist.

Thank you for the answer, but I probably wasn't clear enough with my original question. Apologies 🙏🏾

My main concern is whether subagent process tries to re-bootstrap MCP servers or users the ALREADY existing handles.
I'm a maintainer of https://github.com/chunkhound/chunkhound and we're still in process of implementing true multithreading on top of the underlying vector/embedding storage and before that happens only single instance of the MCP server can run at any given time.
I noticed that when I call the tool via subagents it reports the tool is unavailable and this raises a question of whether it's because it can't load it or something else is going on.
I believe the correct approach long-term would be to let subagents reuse the already running MCP servers if that's not the case right now. Just like (but I know this only anecdotally) claude code does it.

Subagent support is still missing in Codex, and this issue is exactly the gap:

Seems like Subagents dropped in /experimental - I just got this Tip here in the new Codex version:

Tip: NEW: Sub-agents can now be spawned by Codex. Enable in /experimental and restart Codex!

<img width="676" height="151" alt="Image" src="https://github.com/user-attachments/assets/53877cab-848c-4290-95da-bdd113568db2" />

Just Testing ... seems pretty slow and no way to open the Output yet, like CTRL+O you can do on Claude Code.

<img width="676" height="366" alt="Image" src="https://github.com/user-attachments/assets/1b9e2d3b-e72f-4b93-846f-546c45b86d5c" />

> Subagent support is still missing in Codex, and this issue is exactly the gap: Seems like Subagents dropped in /experimental - I just got this Tip here in the new Codex version: > Tip: NEW: Sub-agents can now be spawned by Codex. Enable in /experimental and restart Codex! <img alt="Image" width="676" height="151" src="https://private-user-images.githubusercontent.com/34506214/547864694-53877cab-848c-4290-95da-bdd113568db2.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzA3NDk5NDgsIm5iZiI6MTc3MDc0OTY0OCwicGF0aCI6Ii8zNDUwNjIxNC81NDc4NjQ2OTQtNTM4NzdjYWItODQ4Yy00MjkwLTk1ZGEtYmRkMTEzNTY4ZGIyLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjAyMTAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwMjEwVDE4NTQwOFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWVmMjI1ODFhZmY2NWFiNmRiMGFlYzg4ZDAxZjAyNTkzNjMzMGNlNmI0ZTg2ZmVhYmU5ZTkwNzE3NDcxYmQ1MjgmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.tlPiRE2kDta94fDVDoGCl50zRFS0I4J5qui3Di0yaAE"> Just Testing ... seems pretty slow and no way to open the Output yet, like CTRL+O you can do on Claude Code. <img alt="Image" width="676" height="366" src="https://private-user-images.githubusercontent.com/34506214/547866747-1b9e2d3b-e72f-4b93-846f-546c45b86d5c.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzA3NDk5NDgsIm5iZiI6MTc3MDc0OTY0OCwicGF0aCI6Ii8zNDUwNjIxNC81NDc4NjY3NDctMWI5ZTJkM2ItZTcyZi00YjkzLTg0NmYtNTQ2YzQ1Yjg2ZDVjLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjAyMTAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwMjEwVDE4NTQwOFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWVjODEzMWVmYWM5NTlmYzBhZjNlZTg0NjI5MTE5NGE0YmZjYzI4YmEyNzI1ZGNjNGM4ZDBiYWUwYjRhZGY1MDYmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.hwWxxtLEXtsRTTEy0H1iBQRUuYaieox30GZqEnWjhxE">

you can open the outputs /agent

> > Do subagents use the main agent's handle/connection to access MCP tools/servers ? > > > Subagents have access to everything the parent does. Mcp, skills, and model/reasoning level. > edit: model/reasoning can't be changed even for file exploration, even though it was in the repo. as far as I can tell, that tool doesn't exist. Thank you for the answer, but I probably wasn't clear enough with my original question. Apologies 🙏🏾 My main concern is whether subagent process tries to re-bootstrap MCP servers or users the ALREADY existing handles. I'm a maintainer of https://github.com/chunkhound/chunkhound and we're still in process of implementing true multithreading on top of the underlying vector/embedding storage and before that happens only single instance of the MCP server can run at any given time. I noticed that when I call the tool via subagents it reports the tool is unavailable and this raises a question of whether it's because it can't load it or something else is going on. I believe the correct approach long-term would be to let subagents reuse the already running MCP servers if that's not the case right now. Just like (but I know this only anecdotally) claude code does it.

all good bro.

i have no idea what you're talking about but

this sounds relevant. mcp might not be fully integrated properly in subagents:

https://github.com/openai/codex/commit/87ccc5bbae759629d8a51525c977c56c978e0b09

I have only tested subagents by asking "launch a subagent and ask it what skills it has" and it rightly returned all its skills. so i assumed it working.

but perhaps there's more polish coming.

good luck.

Please forgive me for the second ping everyone :(

Nevermind. Upvote the original lol

Sorry again for the pings.

There is still a continued issue of sub agents either return the output and the orchestrator doesnt read it, or the subagents never auto terminate themselves and decrease the counter to codex can keep using more sub agents. I have noticed both of these issues trying out sub agents today

There is still a continued issue of sub agents either return the output and the orchestrator doesnt read it, or the subagents never auto terminate themselves and decrease the counter to codex can keep using more sub agents. I have noticed both of these issues trying out sub agents today

The orchestrator should close them when all six eventually fill up. I've never seen it fail to, but it does wait until it's used all six, then closes them at once. It's odd for sure. If you're having an issue just steer it via agents or prompting and it'll listen pretty well.

Subagents are working very well for me. We definitely need more than 6 though. I forked codex and now use 12 agents, also made the model and reasoning configurable. Using spark. It's really fun.

May I ask here if someone knows - is there a way to manage transfer/handoff behavior for codex subagents as it works in cagent? Thanks

I don't know if it meets expectation: I explicitly requested to use a subagent for repository analysis, but it still executed in the main session.

I don't know if it meets expectation: I explicitly requested to use a subagent for repository analysis, but it still executed in the main session.

Make sure you have multi agents on in /experimental menu.

Make sure you have multi agents on in /experimental menu.

I had enabled it, but I didn't restart codex. After I restarted, it seems works

I'm going to close this issue because we have pretty robust support in place now for subagents. It's still experimental, but it's getting broad use. For details, refer to this documentation.

We've already received a number of follow-on requests for features that build upon the core subagent implementation. Please keep the ideas coming!

A major missing piece for subagents is per-subagent model/provider/profile selection.

Subagents are where model specialization matters most:

• coordinator on a stronger reasoning model
• workers on a faster/cheaper coding model
• optional routing to custom providers/local models via profiles

I think this should either be part of subagent support directly, or tracked as a linked follow-up issue. There is already precedent for routing bugs/special-path config drift in #5245, so it would be good to define subagent routing semantics explicitly.

A major missing piece for subagents is per-subagent model/provider/profile selection. Subagents are where model specialization matters most: coordinator on a stronger reasoning model workers on a faster/cheaper coding model optional routing to custom providers/local models via profiles I think this should either be part of subagent support directly, or tracked as a linked follow-up issue. There is already precedent for routing bugs/special-path config drift in #5245, so it would be good to define subagent routing semantics explicitly.

Already supported. Check conversion above

Worth to also check https://x.com/yvettec35382/status/2024735963654537690