openai
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 a14a89b1) 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 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.
I have created similar to sub-agent CEO->Manager->Worker According to my test. It can handle much much bigger task
Incase anyone want to try. May visit here https://github.com/thammachet/codex-with-manager-and-ceo
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:)
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:)
No it won't😅 Just auto delegate task The idea is why don't let llm create sub-agent ( as well as there behavior / role by them self ) and use them immediately. So the manager can create 1st worker for frontend 2nd worker for backend 3rd worker for tester ... Similarly and use them without user have to do so
And the CEO can do similarly can spawn many manger etc and push them as well in case it being lazy
Quick visual copy from the TUI
It's quite fun to experiment and interact you can try
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...
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.
@jif-oai For me, sub-agent to receive the command from the main agent.
-
Propose : To scale the work handle it can handle. Or even the "brainstorm" In this setup it should able to create 200000x200000x200000 context needed app.
For example Main Agent : Write a equivalent facebook app.
- Sub Agent : Create Core System
- Sub Sub Agent : Design Backend
- Sub Sub Agent : Design Frontend
- Sub Sub Agent : Validate
- Sub Sub Agent : Review Security
- Sub Agent : Create Page Feature
- Sub Sub Agent : ............................
(The main agent should prompt sub-agent to specialize by them self)