Codex subagents: what they buy you

The mechanism

Codex subagents let a run spawn a separate agent with its own clean context, hand it a task, and get back a summary. The parent keeps its own context small. The child burns through whatever noise the task requires and returns a few paragraphs.

That asymmetry is the entire benefit. Searching a large codebase might mean reading forty files. If the parent does that, its context is now forty files of mostly irrelevant material and it starts forgetting your original instruction. If a subagent does it, the parent receives three sentences and a file path.

Tasks that fit

The shape to look for is wide input, narrow output. Reading lots, returning little.

• Finding where a behaviour is implemented across a repository you do not know.
• Answering a question that spans many files, like which services still call a deprecated endpoint.
• Running a long verification pass and reporting only what failed.
• Independent edits in directories that do not overlap, run in parallel.
• Summarising a large log or test output down to the failing case.

The inverse shape fits badly. If the task needs the full conversation so far, delegating it means writing the whole conversation into the delegation prompt, and you have saved nothing.

Writing a delegation that comes back useful

The most common complaint about Codex subagents is that the result is vague. Nearly always the prompt was vague first. A subagent cannot ask you a follow-up question, so anything you left implicit is lost.

Three things belong in every delegation. State the exact question, not a topic. Say what the answer should look like, including whether you want file paths, line numbers, or a patch. And say what the subagent must not do, particularly whether it may write files.

Compare these. Weak: look into our auth setup. Strong: find every place a session token is created or validated. Return absolute file paths and function names only. Do not edit anything. The second one is answerable. The first one produces an essay.

The costs nobody mentions upfront

Subagents are not free. Each one is a full agent run, so a parent that fans out to five is paying for six loops. On small repositories this is slower and more expensive than just doing the work in one context.

They also lose fidelity at the boundary. Whatever the child understood but did not write down is gone. We have watched a subagent correctly identify a race condition, summarise it as "some concurrency concerns in the worker", and the parent then fix the wrong thing. If a finding matters, ask for it verbatim rather than summarised.

And parallel subagents that write to the same files will clobber each other. There is no lock. Partition by directory before you fan out, or accept that you will be reconciling by hand.

Try this next

Take one question you have asked an agent recently that produced a bloated answer. Rewrite it as a delegation with an explicit output format and a hard no-write rule, run it, and compare the two transcripts. The difference in the parent's context size is the number that should convince you, or not.

If you want help putting this into practice, talk to us.