6 ms·
yes, and you can do it entirely in developer instructions (AGENTS.md/SKILLS.md). No hooks or other executables needed. Check out `codex-subagent-router` for an
by donavanm 11d ago
yes, and you can do it entirely in developer instructions (AGENTS.md/SKILLS.md). No hooks or other executables needed. Check out `codex-subagent-router` for an example. Its overly complicated, and has a few things wrong, but it mostly works. In short:
- Write ~1 paragraph of developer instructions (AGENTS.md): Use subagents for tasks that can be decomposed, worked on in parallel, or delegated. Describe common examples. I put a reference to a "how to use subagents" skill for more details. The "skill" isnt' always read (as subagents arent always useful) which saves some tokens. But you pay the once-per-session read-skill cost when its relevant.
- Describe how to use subagents in ~1 page or less (SKILLS.md): use them for sub tasks. select model size/quality based on task ambiguity, scope, unbounded work, or conflicting requirements. Use reasoning effort for complexity, interdependence, or ambiguous success criteria. How to evaluate complexity & common subtask examples across the spectrum. give tasks a relevant name like "model-family_version_reasoning-effort_task-description" so you can actually understand what theyre doing by name.
- in dev instructions (SKILLS.md) provide a table of agent names (low complexity summarizer, bounded implementation, complex implementation), model+effort (gpt-5.6-luna medium, gpt-5.6-luna high, gpt-5.6-sol medium), and short description of 2-3 task "types" for each.
- Explain they can use "default" or specify their own custom model settings if needed.
- Define your list of subagent profiles in ~/.codex/agents/ which matches names (low_complexity_summarizer.toml) from previous. In each you'll need to set model, reasoning, and `developer_instructions` that describe *how* to do a task, *not what* to do.
Details to know:
- IMO subgent profiles are "task centric" because `developer_instructions` are required. You can't just specify model & reasoning, you also have to give valid developer_instructions that will be merged in to every session/prompt. I address this by defining a few different agents for tasks that are commonly encounted like summarization, synthesis, planning, implementation, etc. The different agent profiles (~2-5 per category) will "scale" the model + reasoning based on the complexity and ambiguity. This work pretty well in practice. And you don't need to over due it, the harness/agent can still launch a "custom" profile that uses the parent sessions developer instructions.
- You need to use agent profiles with codex because "v2" models (terra & sol) can't launch "v1" models (luna). There are a couple of code paths to avoid this, the agent profile is the simplest.
Anyways, write you skill & subagent profiles and it basically "just works".