When Codex sub agents help and when they hurt

The mechanism, briefly

A sub agent is a second agent run started by the first, with its own context window and its own instruction. The parent hands it a task, the sub agent works, and what comes back is a summary rather than the full transcript. Everything the sub agent read stays in its window and disappears when it finishes.

That compression is the whole trade. You get work done without filling the parent's context with fifty file reads. You also get a parent that only knows the conclusion.

Where sub agents earn their keep

The pattern that consistently works is search. You do not know where something lives, the repo is large, and finding out would cost hundreds of lines of grep output in your main session. Send a sub agent, get back three file paths and a sentence, keep working.

Good candidates:

• Locating every call site of a function across a repo you do not know well
• Reading a long log or test output and reporting only the relevant failure
• Answering a question about a dependency's source without pulling it into your session
• Independent review of a diff by a fresh context that has not been arguing with you for an hour

Notice what those share. Read-only, self-contained, and the useful output is small.

Where they go wrong

Writing. Two sub agents editing the same area produce conflicts neither of them can see, and the parent finds out when the tests fail. If you run parallel work that writes, partition by directory and say so explicitly in each instruction.

The subtler failure is lost detail. A sub agent reports "updated the three handlers to use the new client" and the parent believes it. It edited two, decided the third was out of scope, and mentioned that in a sentence the summary dropped. You cannot review what you never saw, so read the actual diff rather than the report. Every time.

The third problem is cost. A sub agent restarts context from nothing, so it re-reads files the parent already had. Delegating a small task can cost more than doing it inline and takes longer in wall-clock time too.

A rule that holds up

Delegate reading, keep writing. If the task's output is information, a sub agent is usually the right call. If the task's output is a change to your repository, do it in the main session where you can watch it, unless the work genuinely partitions into directories that cannot collide.

State the boundary in the instruction rather than hoping. Something like only read, do not edit any file, report file paths and line numbers is worth writing out.

Try it on one task

Next time you are about to run a broad search in your main session, delegate it instead and note what came back. If the summary was enough, that is a pattern to keep. If you had to ask three follow-up questions, the task was not self-contained and belonged inline.

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