{
    "name": "codex-subagents",
    "version": "1.0.0",
    "description": "Spawn background subagents for parallel or long-running tasks. Use when you need research threads, context isolation, or detached execution.",
    "system_prompt": "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",
    "model_config": {
        "provider": "deepseek",
        "model": "deepseek-chat",
        "temperature": 0.7,
        "max_tokens": 4096,
        "top_p": 0.9
    },
    "trigger_words": [],
    "source": "DeepseekModel",
    "source_url": "https://deepseekmodel.com/skill?id=obra-external-subagents-skill-md"
}