codex-subagents

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 Subagents Overview 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 : You cannot send to a running thread. Always wait before sending follow-ups. Use --permissions read-only or --permissions workspace-write (not workspace-read ) For detailed workflow documentation, see reference/workflow.md . When to Use 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. Core Workflow 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 The Running Thread Rule 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 Quick Reference 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 Common Patterns Simple inline prompt codex-subagent start --role researcher --permissions read-only \ --label "quick-task" --prompt "List all exported functions in src/lib/" Multi-line prompt (heredoc) 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 Parallel research # 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 Blocking task # -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 . Cleanup old work # Two-phase: archive completed, then clean old archives codex-subagent archive --completed -- yes codex-subagent clean --older-than-days 30 -- yes Troubleshooting 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 Checklist start has --role , --permissions , --prompt , and --label Permissions are read-only or workspace-write wait before send (never send to running thread) Results captured with --save-response or peek