Multi agent orchestrator

[MasterMind7777777]

Summary

• add the delegate_agent tool so the main Codex assistant can launch sub-agents without user prompts or MCP plumbing
• keep the multi-agent design notes in ai-temp/ temporarily while the architecture settles (they will move or vanish before GA)
• ship a read-only sample Codex home plus ai-temp/example-conversation.md to demonstrate the ideas-provider → critic workflow end-to-end

Why

Deep, specialized operations exhaust the primary context or dilute instructions. By shunting targeted work to sub-agents, we:

• prevent large intermediate artifacts (e.g., heavy JSON, security checklists) from bloating the main conversation
• unlock tailored system prompts, models, and reasoning effort per task without manual toggles
• keep the UI and toolset identical to native Codex: the user still sees the same transcript while the orchestrator manages contexts/config under the hood
• support heterogeneous models/efforts inside a single flow—simple steps on smaller models, heavy audits on higher-effort variants—without manual switching

Status

Work in progress. Delegation already functions for read-only demos, but polished instructions, diagnostics, and more sampling are still ahead.

Usage

# from the repo root
cd codex-rs
env RUSTFLAGS="" cargo build -p codex-cli

# launch the CLI against the sample multi-agent home
CODEX_HOME="$(git rev-parse --show-toplevel)/ai-temp/example-codex-home" target/debug/codex

See ai-temp/example-conversation.md for a complete transcript exercising ideas-provider → critic delegation.

Testing

• cargo build -p codex-cli
• manual CLI session with CODEX_HOME=…/ai-temp/example-codex-home target/debug/codex

[alexx-ftw]

Please make it be able to use a different model than its parent

[MasterMind7777777]

Please make it be able to use a different model than its parent

Will do. My idea is that agents should have its own config.toml to configure them in exactly same way as base codex.

[alexx-ftw]

Please make it be able to use a different model than its parent

Will do. My idea is that agents should have its own config.toml to configure them in exactly same way as base codex.

Sounds good. We should be able to even set a different Base URL, API key and model for the subagents, to combine different providers and have a powerful orchestration system

[towry]

Please make it be able to use a different model than its parent

Will do. My idea is that agents should have its own config.toml to configure them in exactly same way as base codex.

subagent can just use a different profile. Currently I am using Codex as mcp server in claude code with different profile for different models and config.

[MasterMind7777777]

Made a feature that allows switching into a child agent and working in it as in usual Codex, then returning to the main agent with the context collected in the sub agent. For fine-grained control over sub agents. To use, run /agent and select the agent to enter in to.

[alexx-ftw]

Made a feature that allows switching into a child agent and working in it as in usual Codex, then returning to the main agent with the context collected in the sub agent. For fine-grained control over sub agents. To use, run /agent and select the agent to enter in to.

That is a novelty. Haven't seen any other tool do that. Really interesting

[alexx-ftw]

i really hope all this work is appreciated and considered to be merged by the OpenAI Codex team

[alexx-ftw]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting

• @codex fix this CI failure
• @codex address that feedback

[bogzbonny]

Made a feature that allows switching into a child agent and working in it as in usual Codex, then returning to the main agent with the context collected in the sub agent. For fine-grained control over sub agents. To use, run /agent and select the agent to enter in to.

@MasterMind7777777 & @alexx-ftw. Wouldn't it be typical that one wouldn't want this? I could very well me missing something, but as I understand it, one of the core benefits of subagents is you keep the context paired down and clean in the parent agent, it doesn't receive the entire context of the subagent but only a summary which the subagent generates. Alternative to a subagent summary, I could see a highly compacted context also be useful (which effectively acts as a summary). What is the scenario which one would want the full context of the subagent? I suppose if the context is small enough or the LLM is large and good enough it wouldn't matter.

I also wanted to tag a previous discussion I've had on subagents for a different project (bosun-ai/kwaak#352) @MasterMind7777777 maybe you will find some of that discussion useful or relevant

[alexx-ftw]

Made a feature that allows switching into a child agent and working in it as in usual Codex, then returning to the main agent with the context collected in the sub agent. For fine-grained control over sub agents. To use, run /agent and select the agent to enter in to.

@MasterMind7777777 & @alexx-ftw. Wouldn't it be typical that one wouldn't want this? I could very well me missing something, but as I understand it, one of the core benefits of subagents is you keep the context paired down and clean in the parent agent, it doesn't receive the entire context of the subagent but only a summary which the subagent generates. Alternative to a subagent summary, I could see a highly compacted context also be useful (which effectively acts as a summary). What is the scenario which one would want the full context of the subagent? I suppose if the context is small enough or the LLM is large and good enough it wouldn't matter.

I also wanted to tag a previous discussion I've had on subagents for a different project (bosun-ai/kwaak#352) @MasterMind7777777 maybe you will find some of that discussion useful or relevant

Main Agent/Orchestrator still gets a summary. But this solution allows the human to control the subagent when wanted the same as it does with the main Agent, and then go back

[MasterMind7777777]

Made a feature that allows switching into a child agent and working in it as in usual Codex, then returning to the main agent with the context collected in the sub agent. For fine-grained control over sub agents. To use, run /agent and select the agent to enter in to.

@MasterMind7777777 & @alexx-ftw. Wouldn't it be typical that one wouldn't want this? I could very well me missing something, but as I understand it, one of the core benefits of subagents is you keep the context paired down and clean in the parent agent, it doesn't receive the entire context of the subagent but only a summary which the subagent generates. Alternative to a subagent summary, I could see a highly compacted context also be useful (which effectively acts as a summary). What is the scenario which one would want the full context of the subagent? I suppose if the context is small enough or the LLM is large and good enough it wouldn't matter.

I also wanted to tag a previous discussion I've had on subagents for a different project (bosun-ai/kwaak#352) @MasterMind7777777 maybe you will find some of that discussion useful or relevant

Sub agents have their own context that they maintain (separate from parent agent) they only give last thing they produced as per request of main agent. But if you have seen their response of sub agent is bad, not what you expected then you might want to enter that agent to correct it by sending one or multiple clarifications so result that this sub agent provides to main agent is what you been looking for, and main agent using this updated response of subagent can handle final problem.

[bogzbonny]

OHHH I actually misunderstood what was being talked about (whoops!). Basically this is a feature with human interaction inside of the subagent... sounds useful. So is would the workflow as I imagine it:

1. main agent calls subagent
2. subagent produces subpar output, passing its summary back to main agent
3. maybe the main agent begins to work a bit
4. human halts the main agent (ctrl-c)
5. human enters subagent and sends additional prompts to improve the response of the subagent
6. codex starts up again with the new prompt, it starts working from the subagent
7. the subagent sends an additional response to the main agent
   • QUESTION does the main agent still have all of its context (aka context genereted in (3.) OR does the main agent roll back its context to before it got its first response from the subagent (1.)

Is that workflow correct? what happens to the main context on subagent re-prompt?

---

You know what would be interesting too, to be able to have the main agent reprompt the subagent directly if it notices somethings is amiss with the subagent output. For a future PR though.

[john-says-hi]

nice contribution. This sounds like an exciting feature. Hope it works out good.

[MasterMind7777777]

OHHH I actually misunderstood what was being talked about (whoops!). Basically this is a feature with human interaction inside of the subagent... sounds useful. So is would the workflow as I imagine it:

1. main agent calls subagent

2. subagent produces subpar output, passing its summary back to main agent

3. maybe the main agent begins to work a bit

4. human halts the main agent (ctrl-c)

5. human enters subagent and sends additional prompts to improve the response of the subagent

6. codex starts up again with the new prompt, it starts working from the subagent

7. the subagent sends an additional response to the main agent

   • QUESTION does the main agent still have all of its context (aka context genereted in (3.) OR does the main agent roll back its context to before it got its first response from the subagent (1.)

Is that workflow correct? what happens to the main context on subagent re-prompt?

---

You know what would be interesting too, to be able to have the main agent reprompt the subagent directly if it notices somethings is amiss with the subagent output. For a future PR though.

Yah that is how it works. Except context of parent agent is not cleared/altered when you come back from sub agent. Just not sure yet how will it look; if you enter agent after chatting with main agent for long time. Should we really wipe main context to that point where you last used that specific sub agent?
Mb add it as separate opt in feature to replace context instead of add when coming back from sub agent to main agent.

[alexx-ftw]

OHHH I actually misunderstood what was being talked about (whoops!). Basically this is a feature with human interaction inside of the subagent... sounds useful. So is would the workflow as I imagine it:

1. main agent calls subagent

2. subagent produces subpar output, passing its summary back to main agent

3. maybe the main agent begins to work a bit

4. human halts the main agent (ctrl-c)

5. human enters subagent and sends additional prompts to improve the response of the subagent

6. codex starts up again with the new prompt, it starts working from the subagent

7. the subagent sends an additional response to the main agent

   • QUESTION does the main agent still have all of its context (aka context genereted in (3.) OR does the main agent roll back its context to before it got its first response from the subagent (1.)

Is that workflow correct? what happens to the main context on subagent re-prompt?

You know what would be interesting too, to be able to have the main agent reprompt the subagent directly if it notices somethings is amiss with the subagent output. For a future PR though.

Yah that is how it works. Except context of parent agent is not cleared/altered when you come back from sub agent. Just not sure yet how will it look; if you enter agent after chatting with main agent for long time. Should we really wipe main context to that point where you last used that specific sub agent? Mb add it as separate opt in feature to replace context instead of add when coming back from sub agent to main agent.

To me it makes more sense to wipe the entire subagent chat history and reload the main agent chat, just like we do now when resuming a conversation/session

[MasterMind7777777]

OHHH I actually misunderstood what was being talked about (whoops!). Basically this is a feature with human interaction inside of the subagent... sounds useful. So is would the workflow as I imagine it:

1. main agent calls subagent

2. subagent produces subpar output, passing its summary back to main agent

3. maybe the main agent begins to work a bit

4. human halts the main agent (ctrl-c)

5. human enters subagent and sends additional prompts to improve the response of the subagent

6. codex starts up again with the new prompt, it starts working from the subagent

7. the subagent sends an additional response to the main agent

• QUESTION does the main agent still have all of its context (aka context genereted in (3.) OR does the main agent roll back its context to before it got its first response from the subagent (1.)

Is that workflow correct? what happens to the main context on subagent re-prompt?

You know what would be interesting too, to be able to have the main agent reprompt the subagent directly if it notices somethings is amiss with the subagent output. For a future PR though.

Yah that is how it works. Except context of parent agent is not cleared/altered when you come back from sub agent. Just not sure yet how will it look; if you enter agent after chatting with main agent for long time. Should we really wipe main context to that point where you last used that specific sub agent? Mb add it as separate opt in feature to replace context instead of add when coming back from sub agent to main agent.

To me it makes more sense to wipe the entire subagent chat history and reload the main agent chat, just like we do now when resuming a conversation/session

If we do that, there will be no way to bring context back from sub agent in to parent agent. So essentially work user done in sub agent will be lost and will not affect what happens in main agent. It might be useful in some use cases, but in others you might want to bring something back from sub agent to main agent.

[MasterMind7777777]

Another option would be to set up tool for sub agent to communicate to parent agent explicitly. So it would be up to model what to serve upstream. Than you would be able to chat to sub agent without worrying about what context you want to be sent back to parent. But that will lose out on control over agents.

[alexx-ftw]

OHHH I actually misunderstood what was being talked about (whoops!). Basically this is a feature with human interaction inside of the subagent... sounds useful. So is would the workflow as I imagine it:

1. main agent calls subagent

2. subagent produces subpar output, passing its summary back to main agent

3. maybe the main agent begins to work a bit

4. human halts the main agent (ctrl-c)

5. human enters subagent and sends additional prompts to improve the response of the subagent

6. codex starts up again with the new prompt, it starts working from the subagent

7. the subagent sends an additional response to the main agent

• QUESTION does the main agent still have all of its context (aka context genereted in (3.) OR does the main agent roll back its context to before it got its first response from the subagent (1.)

Is that workflow correct? what happens to the main context on subagent re-prompt?

You know what would be interesting too, to be able to have the main agent reprompt the subagent directly if it notices somethings is amiss with the subagent output. For a future PR though.

Yah that is how it works. Except context of parent agent is not cleared/altered when you come back from sub agent. Just not sure yet how will it look; if you enter agent after chatting with main agent for long time. Should we really wipe main context to that point where you last used that specific sub agent? Mb add it as separate opt in feature to replace context instead of add when coming back from sub agent to main agent.

To me it makes more sense to wipe the entire subagent chat history and reload the main agent chat, just like we do now when resuming a conversation/session

If we do that, there will be no way to bring context back from sub agent in to parent agent. So essentially work user done in sub agent will be lost and will not affect what happens in main agent. It might be useful in some use cases, but in others you might want to bring something back from sub agent to main agent.

Maybe I didn't explain myself properly:
I would treat the subagent conversation as a normal conversation internally, but when going back to the parent conversation, summarize it and provide as context to the main agent.
There could be a slash command for going back to main agent chat that summarizes or whatever exit process is done when finishing with the subagent.
This would also allow for the same subagent to be later invoked again if wanted, thus saving up time and tokens, by the main agent

[alexx-ftw]

Another option would be to set up tool for sub agent to communicate to parent agent explicitly. So it would be up to model what to serve upstream. Than you would be able to chat to sub agent without worrying about what context you want to be sent back to parent. But that will lose out on control over agents.

Subagents could be running in the background performing their tasks, and the main agent could probe their progress at any point, or trigger them to provide a summary of the work done so far and whats missing, send them corrective instructions, and also the main agent receive a trigger once the subagent has marked its work as 100% done.
The main agent AND the user should have the capability of forcefully killing a subagent at any point.
Another setting could be how many levels deep can subagents be spawned, defaulted to only 1.

[MasterMind7777777]

OHHH I actually misunderstood what was being talked about (whoops!). Basically this is a feature with human interaction inside of the subagent... sounds useful. So is would the workflow as I imagine it:

1. main agent calls subagent

2. subagent produces subpar output, passing its summary back to main agent

3. maybe the main agent begins to work a bit

4. human halts the main agent (ctrl-c)

5. human enters subagent and sends additional prompts to improve the response of the subagent

6. codex starts up again with the new prompt, it starts working from the subagent

7. the subagent sends an additional response to the main agent

• QUESTION does the main agent still have all of its context (aka context genereted in (3.) OR does the main agent roll back its context to before it got its first response from the subagent (1.)

Is that workflow correct? what happens to the main context on subagent re-prompt?

You know what would be interesting too, to be able to have the main agent reprompt the subagent directly if it notices somethings is amiss with the subagent output. For a future PR though.

Yah that is how it works. Except context of parent agent is not cleared/altered when you come back from sub agent. Just not sure yet how will it look; if you enter agent after chatting with main agent for long time. Should we really wipe main context to that point where you last used that specific sub agent? Mb add it as separate opt in feature to replace context instead of add when coming back from sub agent to main agent.

To me it makes more sense to wipe the entire subagent chat history and reload the main agent chat, just like we do now when resuming a conversation/session

If we do that, there will be no way to bring context back from sub agent in to parent agent. So essentially work user done in sub agent will be lost and will not affect what happens in main agent. It might be useful in some use cases, but in others you might want to bring something back from sub agent to main agent.

Maybe I didn't explain myself properly:

I would treat the subagent conversation as a normal conversation internally, but when going back to the parent conversation, summarize it and provide as context to the main agent.

There could be a slash command for going back to main agent chat that summarizes or whatever exit process is done when finishing with the subagent.

This would also allow for the same subagent to be later invoked again if wanted, thus saving up time and tokens, by the main agent

That is how it works right now. So when main agent invokes sub agent it prompts it, sub agent thinks, does its thing, than finally provides response(final result) we take that final result and feed it in to main agent and main agent continues working.
Later we have option to enter that sub agent run and prompt it more, than it will do it's thinking and produce result
When we done with sub agent and want to go back to main agent we take only user requests and final agent responses to each user request(without intermediate thinking)

[MasterMind7777777]

Another option would be to set up tool for sub agent to communicate to parent agent explicitly. So it would be up to model what to serve upstream. Than you would be able to chat to sub agent without worrying about what context you want to be sent back to parent. But that will lose out on control over agents.

Subagents could be running in the background performing their tasks, and the main agent could probe their progress at any point, or trigger them to provide a summary of the work done so far and whats missing, send them corrective instructions, and also the main agent receive a trigger once the subagent has marked its work as 100% done. The main agent AND the user should have the capability of forcefully killing a subagent at any point. Another setting could be how many levels deep can subagents be spawned, defaulted to only 1.

Not shure if its possible to let model to terminate/correct in-flight agent, it would need to wait for agent turn to finish and than act on it, by accepting result and proceeding or asking follow up to agent.

As per what agents can can spawn
via config.toml

[multi_agent]
agents = ["request_summarizer", "ideas_provider", "critic"]

than sub agent ideas_provider config.toml would have its own agent set up

[multi_agent]
agents = ["creative_ideas", "conservative_ideas"]

so you can set up what sub agents can each agent invoke.

[MasterMind7777777]

Allthough i did add capability to run detached agent that is not awaited by parent agent. So it is none blocking agent run that you may or may not join(only final responce, no intermidiate thinking) in main agent context.

[bogzbonny]

Well apparently new features aren't been considered by openai (see the other multi-agent PR). time 2 ✌️

[etraut-openai]

Thanks for the contribution, and apologies for the slow response. We've received many PRs, and we don't have the bandwidth on the codex team to review all of them.

We've updated our contribution guidelines to clarify that we're currently accepting contributions for bugs and security fixes, but we're not generally accepting new features at this time. We need to make sure that all new features compose well with both existing and upcoming features and fit into our roadmap. If you would like to propose a new feature, please file or upvote an enhancement request in the issue tracker. We will generally prioritize new features based on community feedback.

[towry]

Wasting other people's time

[John0x]

It's probably best to create a fork :)
I would argue that sub-agents are a pretty good selling point.

The "just-every/code" fork is doing pretty good too