Contents
- 01Start From Zero and Choose the Right Surface
- 02Turn Intent Into Verifiable Work
- 03Configure Codex and Teach It the Project
- 04Bound Authority With Sandbox and Approvals
- 05Make the Change and Prove It
- 06Work Across Environments and Worktrees
- 07Delegate With Subagents
- 08Build the Extension Stack
- 09Automate, Embed, and Run Long Work Safely
- 10Capstone: From Command to Receipt
Delegate With Subagents
Split a complex objective into independent lanes, give each agent a bounded contract, and integrate evidence without multiplying confusion.
By the end
A parallel execution plan with clear ownership, communication, acceptance checks, and independent review for each subtask.
Delegate for independence, not appearance
Subagents are valuable when a task can be divided into concrete units that make progress without repeatedly waiting on the same files or decisions. Researching official documentation, mapping a separate subsystem, writing tests for an agreed contract, or reviewing a completed diff are often good lanes. Several agents making intertwined edits to one component are usually not.
Parallelism reduces elapsed time only when coordination cost stays lower than the work saved. Before delegating, ask whether each lane has distinct inputs, a clear output, a bounded file or system scope, and an acceptance check the parent can verify.
Write a subagent contract
A useful subagent request names the objective, relevant context, allowed tools, files or systems in scope, prohibited side effects, required output format, and evidence standard. It should be understandable without the entire parent conversation. Provide the minimum surrounding context needed to make the lane independent.
State whether the agent may edit or is research-only. Shared files are the most important boundary. If two agents must change the same file, sequence them or assign one as the sole writer and have the other return recommendations or a patch for review.
Configure built-in and custom agents
Current Codex includes `default`, `worker`, and `explorer` agents. `explorer` fits read-heavy source mapping; `worker` fits bounded implementation. Create a custom agent only when a repeated lane needs distinct instructions or settings. Personal custom agents live in `~/.codex/agents/`; project agents live in trusted `.codex/agents/`. Each TOML file requires `name`, `description`, and `developer_instructions`.
Project `.codex/config.toml` can set `[agents]` limits. `max_threads` caps concurrent open threads, and `max_depth = 1` lets the root spawn direct children without recursive fan-out. In a project that has chosen the newer permission-profile engine, a custom reviewer can set `default_permissions = ":read-only"`; do not also give that agent `sandbox_mode`. Projects deliberately using the older sandbox engine must stay on that separate mechanism instead. Omitted model, MCP, and skill settings inherit from the parent, while live parent permission overrides still apply to spawned children.
Invoke and steer agents from the task
In the desktop app or CLI, ask Codex explicitly to delegate independent lanes and name the agent or responsibility. Example: ask the built-in explorer to trace the request path without editing, ask one worker to implement only after that map returns, and ask the custom evidence reviewer to audit the final diff read-only. Codex exposes the child threads; in the CLI, `/agent` lets you inspect and switch among them.
Approvals can arrive from an inactive thread. Read the source thread label and open it before deciding. If a child is solving the wrong question, steer it with a corrected objective; if its lane is no longer needed, stop it. In a non-interactive run, a child action that requires a new approval fails because no live approval can surface, so design the parent permissions and child scopes before spawning.
Design complementary lanes
A strong three-lane pattern is explorer, implementer, and verifier. The explorer establishes current evidence and risks. The implementer owns the bounded source change. The verifier checks the finished state against the contract from a fresh perspective. Other useful divisions follow separate components, platforms, datasets, or documentation sources.
Do not delegate the core unresolved product decision and hope a majority vote will resolve it. Agents can compare options and evidence, but the human owner must decide when alternatives produce materially different business behavior or risk.
Communicate at meaningful boundaries
Agents should report when they discover a blocker, a scope conflict, a changed assumption, or a result ready for integration. Constant narration wastes attention, while silent work hides divergence. Ask for compact updates that state evidence, implication, and requested decision.
The parent agent owns the shared plan and integration. If one lane changes a contract used by another, communicate that change before both continue. A written manifest is more reliable than relying on each agent to infer what the others are doing from a changing filesystem.
Verify subagent results at the source
A subagent's final message is a handoff, not proof. Review cited files, commands, tests, URLs, or artifacts. For code, inspect the diff and rerun the relevant checks after integration. For research, open the primary source and confirm that the conclusion is supported and current.
A separate verifier is especially valuable for changes with security, identity, data, payment, or production risk. Independence matters: the verifier should receive the original acceptance criteria and current result, not only the implementer's explanation of why the work is correct.
Working reference
Commands and patterns
Bound project-level agent concurrency
# .codex/config.toml [agents] max_threads = 3 max_depth = 1 interrupt_message = true
Three open threads support a parent plus two focused children without uncontrolled fan-out. Keep depth at one unless nested delegation has a proven need.
Create a read-only evidence reviewer
# .codex/agents/evidence-reviewer.toml name = "evidence_reviewer" description = "Independently checks a finished change against acceptance criteria and cites exact evidence." default_permissions = ":read-only" developer_instructions = """ Do not edit. Read the original acceptance criteria and final diff. Run only read-safe checks available under the selected permission profile. Report each criterion as proven, disproven, or unverified with files and command output. """
Use this file only when every loaded layer and the parent launch command selected the newer permission-profile engine; no older sandbox setting or flag may be active. A project-scoped custom agent becomes available only when the repository's `.codex/` layer is trusted.
Prompt: delegate two independent lanes
Delegate two independent lanes: use explorer to trace the settings save flow without editing; use evidence_reviewer to inspect the current tests and identify missing acceptance coverage. Return both evidence packets before proposing implementation.
Paste this natural-language request into the active Codex conversation. It specifies independence, agent selection, read-only behavior, and the join point.
CLI: inspect active agent threads
/agent
After the agents start, enter this slash command by itself in the interactive CLI to inspect and switch threads.
When the happy path breaks
Failure modes
Symptom
Several agents perform the same investigation and return similar summaries.
Likely cause
The tasks were delegated by role name rather than distinct objective, scope, and output.
Recovery
Redesign lanes around independent questions, components, or proof responsibilities and give each one unique acceptance criteria.
Symptom
Parallel agents create conflicting edits in the same files.
Likely cause
Write ownership and worktree boundaries were not assigned before execution.
Recovery
Stop overlapping writes, preserve both changes, select one owner for each shared file, and move independent work to isolated branches or worktrees.
Symptom
A subagent reports success, but the parent cannot reproduce it.
Likely cause
The handoff omitted environment, commands, file references, artifacts, or remaining assumptions.
Recovery
Require a receipt with exact evidence and independently rerun the critical check in the integrated environment.
Symptom
The parent waits for every lane before using an early result that would unblock the rest.
Likely cause
The plan has no communication boundary for material discoveries or blockers.
Recovery
Define which findings should be sent immediately, update dependent lane contracts, and continue parallel work that remains valid.
Hands-on lab
Run an explorer, implementer, and verifier
Use three complementary subagent lanes to complete one medium-sized change without overlapping ownership.
- 01In a disposable or low-risk repository that has chosen the newer permission-profile engine, confirm no older sandbox setting or launch flag is loaded, then add the bounded `[agents]` config and the `evidence_reviewer` custom agent file from the examples. Start a fresh Codex session so discovery is unambiguous.
- 02Ask Codex to list available built-in and project agents, then run the invocation example. Open `/agent` and inspect each thread's objective and activity.
- 03Steer one child with a narrower file boundary while it is active, then stop a lane you deliberately make redundant. Record how the parent reports both changes.
- 04Write the parent objective, shared acceptance criteria, authority boundary, and integration owner for a real medium-sized change.
- 05Assign the built-in explorer to map source and tests without editing; use that evidence to give one worker a narrow branch or worktree and file scope.
- 06Give `evidence_reviewer` the original criteria and completed diff. Require proven, disproven, or unverified for every criterion.
- 07Review each handoff at its cited source, rerun the integrated checks, and record whether parallelism improved elapsed time, quality, or risk.
Deliverable: A delegation manifest, three evidence-backed handoffs, an integrated result, and a short parallelism retrospective.
Reusable artifact
Subagent delegation manifest
A contract for parallel work that makes ownership, evidence, and integration explicit.
Parent objective: [shared outcome] Shared acceptance criteria: [pass/fail checks] Lane name and purpose: [one concrete responsibility] Inputs: [files, links, decisions, artifacts] Allowed actions: [read/edit/test/connect] Owned scope: [files, components, systems] Prohibited overlap or side effects: [boundaries] Expected output: [format and location] Evidence required: [paths, commands, sources, screenshots] Send an early update when: [blocker, scope conflict, changed contract] Integration owner and order: [who combines what when]
Before you move on
Receipt checklist
- Every subagent has a concrete, bounded, independently useful objective.
- Write ownership and environment boundaries prevent overlapping mutation.
- Material blockers and contract changes are communicated before dependent work proceeds.
- Each handoff includes source-level evidence rather than only a narrative summary.
- The integrated result is reviewed and tested independently of lane-level success.
Primary sources
