jpcaparas codex-subagents
Use Codex subagents deliberately for authorized parallel delegation while keeping the main thread clean, accountable, and model-neutral.
Decision Tree
Before applying this skill, answer these gates in order:
Not running in Codex CLI or Codex app: Stop. Do not simulate Codex subagents with Claude advisor, web search, another model, another harness, or manual background prompts.
Running in Codex IDE extension, Codex web/cloud, or an unknown Codex-like surface: Stop. The public docs currently surface subagent activity in Codex CLI and Codex app; update this skill from official docs before extending it to another surface.
User did not explicitly ask for subagents, parallel agents, delegation in parallel, one agent per point, multi-agent work, or custom Codex agents: Do not spawn subagents. Continue normally. Mention subagents only if the user asks how to speed up or parallelize the work.
User did explicitly ask for subagents or parallel agent work: Read
references/delegation-policy.md, do a short local plan first, keep the immediate critical-path task local, and delegate only bounded work that can run independently.User asks about setup, custom agents,
/agent, sandbox behavior,[agents]config, or why a subagent did or did not run: Readreferences/codex-mechanics.mdbefore answering or editing config.User asks for prompt examples or repeatable delegation shapes: Read
references/patterns.mdand adapt the closest pattern.
Quick Reference
| Situation | Action |
|---|---|
| Parallel code review requested | Spawn focused reviewers after inspecting the diff shape; split by risk category and ask for file-referenced findings |
| Large research or codebase exploration requested | Spawn read-only explorers for independent questions; keep synthesis in the main thread |
| Multi-step implementation requested | Split only when write sets are disjoint; assign ownership and tell workers not to revert others |
| Tests/log triage can run beside implementation | Delegate the concrete test/log question while the main agent continues non-overlapping work |
| Security, permissions, sandboxing, secrets, or production data | Gather evidence first, then use specialized subagents only if they reduce risk without exposing unnecessary sensitive content |
| Recurring failure after two credible attempts | Delegate an independent diagnostic pass before another speculative fix |
| Completion check for risky work | Spawn a reviewer/checker pass before declaring done, then verify locally |
| No explicit subagent request | Do not spawn; subagent workflows are not automatic |
| Unknown or non-Codex harness | Exit the skill and do not emulate subagents |
Operating Rules
- Use this skill only in Codex CLI or Codex app sessions where subagent workflows are available.
- Treat explicit user authorization as mandatory. "Be thorough", "research deeply", or "review carefully" is not enough by itself.
- Plan before delegating. Identify the immediate task the main agent should do locally and the sidecar tasks that can run in parallel.
- Prefer subagents for read-heavy, noisy, or independently verifiable work: exploration, triage, tests, log analysis, review, summarization, and completion checks.
- Be cautious with write-heavy parallelism. Use it only when each worker has a clear, disjoint file/module ownership boundary.
- Keep model choice open-ended. Inherit the parent session model by default; steer capability, speed, or reasoning effort only when the task actually needs it and avoid hard-coded model-version policy.
- Keep sandbox and approval expectations explicit. Subagents inherit the parent sandbox policy, and child approval failures can surface back to the parent workflow.
- Prompt subagents for distilled outputs: findings, changed files, commands run, confidence, blockers, and exact file references. Do not ask them to paste noisy logs unless needed.
- Integrate results critically. The main agent remains responsible for final decisions, conflict resolution, local verification, and the user-facing answer.
- Close or ask Codex to close completed agent threads when they are no longer needed.
Reading Guide
| Need | Read |
|---|---|
| Decide whether to spawn, skip, split, wait, or review | references/delegation-policy.md |
Codex availability, built-in/custom agents, sandbox inheritance, /agent, and [agents] config |
references/codex-mechanics.md |
| Prompt templates for reviews, research, implementation, triage, and completion checks | references/patterns.md |
| Official-source summary and refresh points | references/source-notes.md |
| Conservative local Codex preflight | scripts/detect_codex_surface.py |
Gotchas
- Subagents are explicit opt-in in Codex. A skill can pressure correct use after authorization, but it should not silently spawn agents for ordinary work.
- More agents can make work slower or more expensive when tasks are coupled. Parallelism helps only when the work can proceed independently.
- Recursive delegation is easy to overdo. Keep spawned agents shallow unless the user explicitly needs deeper fan-out and understands the cost.
- A subagent summary is evidence, not proof. Verify high-risk claims against files, tests, or docs before finalizing.
- Model names age. Write policy around task demands and inheritance rather than freezing a specific model version into the skill.
- Sandbox permissions are inherited. A read-only or approval-gated parent workflow can still block a child action, especially in non-interactive runs.