Codex Subagent Skill

Spawn autonomous subagents to offload context-heavy work. Subagents burn their own tokens, return only final results.

Golden Rule: If task + intermediate work would add 3,000+ tokens to parent context → use subagent.

Intelligent Prompting

Critical: Parent agent must provide subagent with essential context for success.

Good Prompting Principles

1. Include relevant context - Give the subagent thorough context
2. Be specific - Clear constraints, requirements, output format
3. Provide direction - Where to look, what sources to prioritize
4. Define success - What constitutes a complete answer

Examples

❌ Bad: "Research authentication"

✅ Good: "Research authentication in this Next.js codebase. Focus on: 1) Session management strategy (JWT vs session cookies), 2) Auth provider integration (NextAuth, Clerk, etc), 3) Protected route patterns. Check /app, /lib/auth, and middleware files. Return architecture summary with code examples."

❌ Bad: "Search for Codex SDK"

✅ Good: "Find the most recent Codex SDK documentation and summarize key updates. Focus on: 1) Installation/quickstart, 2) Core API methods and parameters, 3) Breaking changes or deprecations. Prioritize official OpenAI docs and release notes. Return a concise summary with citations."

❌ Bad: "Find API endpoints"

✅ Good: "Find all REST API endpoints in this Express.js app. Look in /routes, /api, and /controllers directories. For each endpoint document: method (GET/POST/etc), path, auth requirements, request/response schemas. Return as markdown table."

Prompting Template

[TASK CONTEXT]
You are researching/analyzing [SPECIFIC TOPIC] in [LOCATION/CODEBASE/DOMAIN].

[OBJECTIVES]
Your goals:
1. [1st objective with specifics]
2. [2nd objective]
3. [3rd objective if needed]

[CONSTRAINTS]
- Focus on: [specific areas/files/sources]
- Prioritize: [what matters most]
- Ignore: [what to skip]

[OUTPUT FORMAT]
Return: [exactly what format parent needs]

[SUCCESS CRITERIA]
Complete when: [specific conditions met]

Model Selection

Use Mini Model (gpt-5.1-codex-mini + medium)

Pure search only - no additional work after gathering info.

Bash (Linux/macOS)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' \
  "Search web for [TOPIC] and summarize findings"

PowerShell (Windows)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' `
  "Search web for [TOPIC] and summarize findings"

Inherit Parent Model + Reasoning

Multi-step workflows - search + analyze/refactor/generate:

Bash (Linux/macOS)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "Find auth files THEN analyze security patterns and propose improvements"

PowerShell (Windows)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "Find auth files THEN analyze security patterns and propose improvements"

Decision Logic

Is task PURELY search/gather?
├─ YES: Any work after gathering?
│  ├─ NO → mini model
│  └─ YES → inherit parent
└─ NO → inherit parent

Basic Usage

Bash (Linux/macOS)

# Get parent session settings (respects active profile; falls back to top-level)
# NOTE: codex-parent-settings.sh prints two lines; use mapfile to avoid empty REASONING.
mapfile -t _settings < <(scripts/codex-parent-settings.sh)
MODEL="${_settings[0]}"
REASONING="${_settings[1]}"

# Spawn subagent (inherit parent)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "DETAILED_PROMPT_WITH_CONTEXT"

# Safer prompt construction (no backticks / command substitution)
PROMPT=$(cat <<'EOF'
[TASK CONTEXT]
You are analyzing /path/to/repo.

[OBJECTIVES]
1. Do X
2. Do Y

[OUTPUT FORMAT]
Return: path - purpose
EOF
)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "$PROMPT"

# Pure search (use mini)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' \
  "SEARCH_ONLY_PROMPT"

# JSON output for parsing
codex exec --dangerously-bypass-approvals-and-sandbox --json "PROMPT" | jq -r 'select(.event=="turn.completed") | .content'

PowerShell (Windows)

# Get parent session settings (respects active profile; falls back to top-level)
$scriptPath = Join-Path $env:USERPROFILE ".codex\skills\codex-subagent\scripts\codex-parent-settings.ps1"
$settings = & $scriptPath
$MODEL = $settings[0]
$REASONING = $settings[1]

# Spawn subagent (inherit parent)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "DETAILED_PROMPT_WITH_CONTEXT"

# Use here-string for multi-line prompts (avoids escaping issues)
$PROMPT = @'
[TASK CONTEXT]
You are analyzing /path/to/repo.

[OBJECTIVES]
1. Do X
2. Do Y

[OUTPUT FORMAT]
Return: path - purpose
'@

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  $PROMPT

# Pure search (use mini)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' `
  "SEARCH_ONLY_PROMPT"

# Method 1 (Recommended): Use -o to output directly to file
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  -o output.txt "PROMPT"
$content = Get-Content -Path output.txt -Raw

# Method 2: Parse JSONL event stream
$jsonl = codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --json "PROMPT"
$events = $jsonl -split "`n" | Where-Object { $_ } | ForEach-Object { $_ | ConvertFrom-Json }
$content = $events |
    Where-Object -Property type -EQ "item.completed" |
    Where-Object { $_.item.type -eq "agent_message" } |
    Select-Object -ExpandProperty item |
    Select-Object -ExpandProperty text

Parallel Subagents (Up to 5)

Spawn multiple subagents for independent tasks:

Bash (Linux/macOS)

# Research different topics simultaneously
codex exec --dangerously-bypass-approvals-and-sandbox -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" "Research topic A..." &
codex exec --dangerously-bypass-approvals-and-sandbox -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" "Research topic B..." &
wait

PowerShell (Windows)

Use PowerShell Jobs for parallel execution with -o to output to separate files:

# Parallel execution with file output
$job1 = Start-Job -ScriptBlock {
    param($m, $r, $out)
    codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
      -m $m -c "model_reasoning_effort=`"$r`"" -o $out "Research topic A..."
} -ArgumentList $MODEL, $REASONING, 
List & Monetize Your Skill
Submit your Claude Code skill and start earning
Get started →