Subagents and task delegation

Back to the Codex learning hub

Goal and preparation

Lessons and resources mentioned here: First project

A subagent is delegated a defined part of the work and reports back to the parent. It is not automatically an isolated Git repository, and opening two windows does not create coordination. Parallel tasks need their own inputs, scopes and outputs without waiting for another worker's edits. Both workers in this exercise read only, avoiding competing writes to the same code.

Step 1: Check materials and baseline

Open the five files index.html, style.css, app.js, core.mjs and core.test.mjs in your complete reference copy, not the deliberately broken start/broken variants. On Windows, macOS and Linux, verify the terminal working directory and run the same test command. No npm packages or external database are required. Save the result and version so later findings can be compared against the baseline.

node --version
node --test core.test.mjs

The provided reference currently has three top-level tests and should pass. That count belongs to this material, not arbitrary repositories. If Node or core.test.mjs is missing, resolve CLI troubleshooting and path issues before delegation. Do not ask a worker to invent a similar project when files are missing, as that changes the review target.

Step 2: Explicitly request two subagents

Select the practice folder in the parent desktop, CLI or IDE task and submit the prompt below. Current local Codex delegates when directly requested or instructed by applicable AGENTS.md/Skills; this prompt explicitly asks for two. Inherit the parent's model and effort instead of hardcoding a model unavailable to the account. Each worker consumes model/tool usage; two small bounded reviews are easier to verify than unlimited worker creation.

Use exactly two subagents for a read-only review of this Small Steps reference copy.
Do not spawn additional subagents or modify files.

Agent A: Read core.mjs. Map addTask, visibleTasks and decodeTasks.
For each function, report its input, behavior, failure or boundary handling, and file/symbol evidence.

Agent B: Read core.test.mjs. Map existing test coverage to those same functions.
Distinguish covered cases from possible missing cases; do not invent a bug just because a test is absent.

Parent: Wait for both reports. Verify cited symbols and reconcile disagreements.
Run node --test core.test.mjs once in the practice directory after collecting the reports.
Return a compact evidence table, actual test result and unverified claims.
If subagents are unavailable, say so; do not present a single-agent answer as delegated work.

Include the reference copy's absolute root and baseline result with the request, and ask each report to identify its read paths. Two reports naming core.mjs may concern different checkouts; match both to the same expected copy. Label the three-pass baseline as the parent's earlier record, not a test run by A or B.

Both workers can start together; the parent runs tests once afterward to avoid duplication.

Step 3: Inspect, steer and stop work

On desktop, open individual workers from activity in the parent and inspect files and status. In the interactive CLI, /agent switches views; it is not a shell command named codex agent. In an IDE with the background-agent panel, expand it or open a worker. Ask the parent to steer or stop a specific worker. If controls are absent, check version/surface support rather than inventing a completion list.

/agent

Tell Agent A to include duplicate task IDs in its analysis and keep the work read-only.
Wait for the updated evidence before the final summary.

Have the parent send the addition to A and verify that A's update discusses addTask's duplicate-ID handling. Confirm the worker name/activity instead of assuming text entered in another window reaches the intended recipient. To stop B, request that explicitly while preserving evidence and marking unfinished work unverified. Stopping does not roll back changes. This read-only exercise should leave no file diff; investigate any unexpected edit separately.

Step 4: Verify evidence, not just completion counts

In the reference, addTask trims text, validates length and IDs and returns a new array; visibleTasks handles active/completed filters; decodeTasks rejects malformed data and duplicate IDs. The parent should verify A against those functions and B against the actual tests. If B claims duplicate IDs are untested, distinguish adding from decoding stored data. Resolve disagreement through evidence rather than choosing the longer report.

The parent then runs the baseline tests once and records the actual exit/result. Include claim, file/symbol, test evidence and verified/unverified status. Code inspection can establish some behavior without browser testing, while a coverage suggestion is not necessarily a current bug. Separate those states to decide whether the next step is another test, reproduction or a fix.

Optional: Save a narrowly scoped custom role

For repeated reviews, create .codex/agents/data-reader.toml in a trusted practice project after checking that it does not already exist. This is agent TOML configuration, not AGENTS.md, and existence does not spawn a worker. Save the complete example, explicitly request data_reader in a new task and inspect its behavior. This optional extension is not a prerequisite for the two-worker exercise.

name = "data_reader"
description = "Inspect Small Steps data invariants with file and symbol evidence."
sandbox_mode = "read-only"
developer_instructions = """
Read core.mjs and report inputs, invariants and error handling.
Do not edit files, invoke external services or spawn other agents.
Cite the relevant functions and distinguish confirmed behavior from assumptions.
If the file is missing, report the missing path and stop.
"""

The example omits a model to inherit available settings. Workers inherit the parent's current permissions; interactive CLI runtime overrides are reapplied, so the file's read-only default is not an unconditional override of live permissions. Check the parent's Permission mode before delegation and retain read-only instructions. To undo the extension, remove only your added role file and verify a new task without deleting the entire .codex folder.

Failures, boundaries and next step

If no subagent is created, check the explicit request, supported version/surface and capacity occupied by existing workers; do not substitute role-play for actual delegation. For concurrent edits, stop writes, inspect the diff and move to distinct workspaces or a sequence using Worktrees. If a worker needs authentication or approval, the parent should identify the source and blocked step rather than silently retrying a denied action with greater access.

Retain activity from two real workers, their evidence, response to one steering message, parent reconciliation/test result and confirmation that all five files remain unchanged. A deliberately stopped B can be a separate run labeled stopped, not two completed reports. Role configuration and reference code can be checked statically; this text does not claim agents were spawned on your account. Unoperated clients/platforms are officially documented. Continue to Subagent quality to assess plausible but unsupported reports.

Back to the Codex learning hub

Read the full description

Bounded tasks to Subagents to Review

• AI tools
• Tutorials
• Codex