Subagent Support

What feature would you like to see?

Summary

Request for official subagent functionality to be implemented in codex.

Background

This codebase https://github.com/bluxolguin/codex.git branch bluxolguin/subagents currently has experimental agent management features (see commit a14a89b) that demonstrate the foundation for subagent functionality. This includes:

Agent storage system in codex-rs/core/src/agents_store.rs
TUI integration for agent creation
Basic prompt templating for agent definitions

Motivation

Subagents would provide several key benefits:

Specialized Expertise: Different agents for different domains (frontend, backend, DevOps, etc.)
Context Isolation: Separate concerns and maintain focused conversations
Workflow Optimization: Task-specific agents can provide more targeted assistance
User Productivity: Quick access to specialized knowledge without context switching

Proposed Implementation

Based on the existing experimental code, the feature should include:

Core Components

Agent registry and persistence (partially implemented in agents_store.rs)
Agent selection interface in TUI
Agent-specific prompt injection system
Context isolation between agents

User Interface

Agent creation workflow (basic version exists)
Agent switching within conversations
Agent management command (/agents)
Visual indicators showing active agent

Agent Types

Consider supporting common agent archetypes:

code-reviewer: Focuses on code quality and best practices
architect: System design and architectural guidance
debugger: Problem diagnosis and troubleshooting
documentation: Writing and maintaining documentation
test-writer: Test creation and coverage analysis

Technical Considerations

Agent definitions should be stored in ~/.codex/agents.json
Subagent prompts should augment, not replace, base codex instructions
Need clear boundaries between agent capabilities
Should integrate seamlessly with existing tool usage

Current Status

Experimental implementation exists on https://github.com/bluxolguin/codex.git branch bluxolguin/subagents with basic agent storage and creation capabilities. This provides a solid foundation for official implementation.

Success Criteria

Users can create custom agents with specific prompts
Agent switching is intuitive and fast
Agents maintain their specialized focus throughout conversations
Feature integrates seamlessly with existing codex workflows
Documentation and examples for creating effective agents

References

Existing implementation: codex-rs/core/src/agents_store.rs
TUI integration: codex-rs/tui/src/chatwidget.rs:882-984
Agent creation prompt: codex-rs/tui/prompt_for_agent_creation.md

Are you interested in implementing this feature?

No response

Additional information

No response

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

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

@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

want

much need

Need this for sure to preserve context

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!

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

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:

87ccc5b

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

Navigation Menu

Repository navigation

Subagent Support #2604

What feature would you like to see?

Summary

Background

Motivation

Proposed Implementation

Core Components

User Interface

Agent Types

Technical Considerations

Current Status

Success Criteria

References

Are you interested in implementing this feature?

Additional information

83 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Subagent Support #2604

Description

What feature would you like to see?

Summary

Background

Motivation

Proposed Implementation

Core Components

User Interface

Agent Types

Technical Considerations

Current Status

Success Criteria

References

Are you interested in implementing this feature?

Additional information

Activity

seratch commented on Aug 25, 2025

Git-on-my-level commented on Sep 24, 2025

adbl commented on Oct 13, 2025

dKosarevsky commented on Nov 6, 2025

tekn0x commented on Nov 8, 2025

Goldziher commented on Nov 8, 2025

r0ck40k commented on Nov 9, 2025

ACSKamloops commented on Nov 9, 2025

Lerty commented on Nov 11, 2025

markojak commented on Nov 12, 2025

83 remaining items

am-will commented on Feb 10, 2026

am-will commented on Feb 10, 2026

am-will commented on Feb 13, 2026

kanlanc commented on Feb 15, 2026

am-will commented on Feb 15, 2026

ThePlenkov commented on Feb 15, 2026

Reekin commented on Feb 19, 2026

am-will commented on Feb 19, 2026

Reekin commented on Feb 19, 2026

etraut-openai commented on Feb 23, 2026

oxysoft commented on Mar 9, 2026

acgxv commented on Mar 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions