subagentport

Codex subagents and custom agents

Create a Codex custom agent TOML file with name, description, developer_instructions and model settings, and learn what Codex agents inherit.

Last checked against official docs: 2026-10-20. Codex subagents, config reference. 


  





  

    
Locations

    
Personal ~/.codex/agents/*.toml, project .codex/agents/*.toml. One agent per file.

    
Required TOML fields

    
name, description, and developer_instructions are required.

    
What agent files cannot override

    
Per current docs: parent permissions, provider, MCP, sandbox_mode, and approval_policy are inherited; agent files do not override them.

    
Allowed characters in name are not documented (unverified). This generator uses snake_case names to match examples.

  

  

  
FAQ

  

    
        
Why does Codex not pick my agent automatically?

        
Codex docs say delegation happens when you ask directly or when AGENTS.md or skill instructions request it. Description guides humans and docs, not automatic picking in local Codex.

      
        
Can a Codex subagent be read-only?

        
Not as a separate sandbox. developer_instructions can say not to edit files, but the parent permissions still apply. features.shell_tool = false is the documented capability toggle.

      
        
Where is max_threads?

        
Global subagent concurrency is configured under [agents] in config.toml as max_concurrent_threads_per_session (legacy alias max_threads), not in per-agent TOML files.

      
        
How do I set a default subagent model?

        
Use agents.default_subagent_model and agents.default_subagent_reasoning_effort in config.toml under [agents]. Per-agent model in the TOML file overrides when set.

      
        
Can agent files override sandbox or MCP?

        
Current Codex docs say sandbox_mode, approval_policy, model_provider and mcp_servers in an agent file do not override the parent. Treat older indexed copies as stale.