Subagent Support

[bluxolguin]

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:

1. Specialized Expertise: Different agents for different domains (frontend, backend, DevOps, etc.)
2. Context Isolation: Separate concerns and maintain focused conversations
3. Workflow Optimization: Task-specific agents can provide more targeted assistance
4. 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

[seratch]

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

[cognitive-glitch]

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

[Git-on-my-level]

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.

[adbl]

@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.

[dKosarevsky]

when?

[tekn0x]

This is much needed.