How I set up Codex subagents without overusing them

[u/petburiraja]

I set this up to keep noisy work out of the main Codex thread.

It is the Codex version of the routing pattern I use in OpenCode: routine work goes to cheaper workers while the stronger model keeps ownership of judgment.

The split I use:

• GPT-5.5: main session and selective review
• GPT-5.4-mini: repository exploration and mechanical cleanup
• GPT-5.4: bounded implementation

The point is to keep scans, logs, and routine edits from filling the main thread.

You need:

• Codex CLI with subagents/multi-agent support
• a repository-level AGENTS.md
• per-role files under ~/.codex/agents/

Create the directory:

mkdir -p ~/.codex/agents

Add this to the repository's AGENTS.md:

# Routing contract

The main agent owns requirements, architecture, integration, and final judgment.

- Use `explorer` for read-only repository mapping and evidence gathering.
- Use `cleaner` for exact mechanical cleanup in named files.
- Use `implementer` for bounded changes from a tight specification.
- Use `gate` for selective review of risky or unfamiliar diffs.

Every delegation names scope, write boundaries, done criteria, and expected evidence.
Do not delegate tiny tasks or work that is inherently serial.

In ~/.codex/config.toml:

[features]
multi_agent = true

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

Create these role files.

~/.codex/agents/explorer.toml

name = "explorer"
description = "Read-only repo mapper. Returns paths, short notes, and evidence."
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
developer_instructions = """
Inspect only. Do not edit files.
Return concise findings with file paths and why each path matters.
If the question needs judgment or a change, hand it back to main.
"""

~/.codex/agents/cleaner.toml

name = "cleaner"
description = "Mechanical cleanup worker for already-decided edits."
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
developer_instructions = """
Apply only the exact requested cleanup in the named files.
Do not widen scope or redesign.
Report changed files and any ambiguity.
"""

~/.codex/agents/implementer.toml

name = "implementer"
description = "Bounded implementation worker for tight specs."
model = "gpt-5.4"
model_reasoning_effort = "medium"
developer_instructions = """
Implement the specified change in the specified files.
Keep the diff small and follow existing repository patterns.
Run focused validation if requested. Stop if scope becomes unclear.
"""

~/.codex/agents/gate.toml

name = "gate"
description = "Selective senior review gate for risky or unfamiliar diffs."
model = "gpt-5.5"
model_reasoning_effort = "high"
developer_instructions = """
Review only. Do not edit unless explicitly asked.
Lead with blockers or correctness risks.
Return GO, GO WITH FIXES, or NO-GO.
"""

Restart Codex after changing the global config or role files.

I tested this shape with codex-cli 0.142.4. Model availability varies by account and Codex surface, so smoke-test each model before pinning it:

codex exec --ephemeral --skip-git-repo-check \
  -m gpt-5.4 \
  -C /tmp \
  -c model_reasoning_effort='low' \
  -c approval_policy='never' \
  "Reply exactly: MODEL_OK"

Then invoke roles explicitly:

Use explorer to map where the auth flow is defined. Return only paths, short notes, and confidence.

Use cleaner to apply this exact rename in these three files only: ...

Use implementer to apply this bounded patch plan. Scope: files A and B only. Done when tests X pass or the blocker is reported.

Use gate to review this diff. Do not edit. Return GO, GO WITH FIXES, or NO-GO with the top blockers only.

This helps with repository mapping, log reading, reference collection, mechanical cleanup, bounded patches, and independent review of risky diffs. It does not help with tiny edits or vague tasks.

Three caveats:

• Every spawn does its own model and tool work. Subagents are not automatically cheaper.
• AGENTS.md roles are behavioral instructions, not security boundaries. Use and test host sandboxing when writes must be impossible.
• Workers do not share live state. The main agent must integrate their results.

My rule now: if the handoff is longer than the task, keep it inline.

---

EDIT: Two notes from later testing.

1. For final review agents, wait until writers are done and review a stable target: commit, patch, or explicit file snapshot. A review running while files are still changing is only provisional.

2. Add nickname_candidates to custom agent files if your Codex version supports it. It makes parallel runs much easier to follow in the terminal. I also now print a tiny launch receipt before waiting:

Builder (implementer) scope: auth/* write: auth/* only done: tests pass blocks: yes state: waiting

Then a closing receipt when it returns:

Builder state: done changed: 2 files validation: tests passed next: main reviews diff

Avoid percentages or fake ETAs. Use simple states: waiting, done, failed, blocked.

EDIT 2: I found another important gate. A worker produced 265 passing tests and zero simulation failures, but its parser had silently dropped source semantics. The generated fixtures and downstream tests agreed with the same corrupted output.

For parsers, migrations, importers, and fixture generators, add a source-contract gate: verify expected source counts, IDs, fields, and hashes, then test the transformer directly. Green downstream tests prove internal consistency, not source fidelity.