// Spawn background subagents for parallel or long-running tasks. Use when you need research threads, context isolation, or detached execution.
| name | codex-subagents |
| description | Spawn background subagents for parallel or long-running tasks. Use when you need research threads, context isolation, or detached execution. |
codex-subagent offloads work to background threads so your main context stays lean. Threads run detached by default; use wait/peek to check results.
Critical rules:
--permissions read-only or --permissions workspace-write (not workspace-read)For detailed workflow documentation, see reference/workflow.md.
| Situation | Why subagents help |
|---|---|
| Parallel research tasks | Multiple threads run simultaneously |
| Context would bloat | Research stays in separate thread |
| Long-running work | Detached execution, check later |
Don't use for: Quick inline questions, tightly-coupled work needing your current state.
1. start with --prompt (inline text or stdin)
2. wait/peek → check result
3. send → resume with follow-up (ONLY after thread stops)
4. archive/clean → lifecycle management
You CANNOT send to a running thread. This is the #1 mistake.
# WRONG - thread might still be running
echo "followup" | codex-subagent send thread-abc --prompt -
# RIGHT - wait first, then send
codex-subagent wait --threads thread-abc
echo "followup" | codex-subagent send thread-abc --prompt -
Resumable statuses: completed, failed, stopped, waiting
| Command | Purpose | Key flags |
|---|---|---|
start | Launch new thread | --role, --permissions, --prompt, --label, -w |
send | Resume stopped thread | <thread-id>, --prompt, -w |
peek | Read newest unseen message | <thread-id>, --save-response |
log | Full history | <thread-id>, --tail, --json |
status | Thread summary | <thread-id> |
wait | Block until threads stop | --threads, --labels, --all, --follow-last |
list | Show threads | --status, --label, --role |
archive | Move completed to archive | --completed, --yes, --dry-run |
clean | Delete old archives | --older-than-days, --yes |
Prompt input: --prompt "text" for simple prompts, --prompt - reads from stdin (for multi-line), -f/--prompt-file for files
Positional thread IDs: peek abc123 works like peek -t abc123
codex-subagent start --role researcher --permissions read-only \
--label "quick-task" --prompt "List all exported functions in src/lib/"
cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "auth-research" --prompt -
Research authentication patterns in this codebase:
1. Find all auth-related files
2. Document the auth flow
3. Note any security concerns
EOF
# Launch multiple researchers
cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "API: Stripe" --prompt -
Research Stripe API authentication methods and best practices
EOF
cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "API: Twilio" --prompt -
Research Twilio API authentication methods and best practices
EOF
# Wait for all, see results
codex-subagent wait --labels "API:" --follow-last
# -w blocks until complete (may take minutes)
cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --prompt - -w --save-response result.txt
Analyze error handling patterns in src/
EOF
cat result.txt
Warning: -w blocks for as long as the agent runs. For long tasks, prefer detached mode with wait --follow-last.
# Two-phase: archive completed, then clean old archives
codex-subagent archive --completed --yes
codex-subagent clean --older-than-days 30 --yes
| Problem | Cause | Fix |
|---|---|---|
| "profile does not exist" | Wrong permissions | Use read-only or workspace-write (not workspace-read) |
| "not resumable" error | Thread still running | wait first, then send |
| "different controller" | Wrong session | Use --controller-id or check list |
| Thread disappeared | Was archived | Check archive dir or re-run task |
start has --role, --permissions, --prompt, and --labelread-only or workspace-writewait before send (never send to running thread)--save-response or peek