codex-subagent

Codex サブエージェントスキル

コンテキストを大量に消費する作業を任せるため、自律型サブエージェントを起動します。サブエージェントは自身のトークンを消費し、最終結果のみを返します。

黄金律： タスクと中間作業によって親のコンテキストに3,000トークン以上追加される場合は、サブエージェントを使用します。

インテリジェントなプロンプト作成

重要：親エージェントは、成功に必要なコンテキストをサブエージェントに提供する必要があります。

適切なプロンプト作成の原則

1. 関連するコンテキストを含める - サブエージェントに十分なコンテキストを提供します
2. 具体的にする - 制約、要件、出力形式を明確にします
3. 方向性を示す - 調査する場所と、優先する情報源を伝えます
4. 成功の定義を示す - 完全な回答とは何かを定義します

例

❌ 悪い例： 「認証について調査」

✅ 良い例： 「この Next.js コードベースの認証について調査してください。以下に注目してください：1）セッション管理方式（JWT とセッション Cookie のどちらか）、2）認証プロバイダーの統合（NextAuth、Clerk など）、3）保護されたルートのパターン。/app、/lib/auth、およびミドルウェアのファイルを確認してください。コード例を含むアーキテクチャの概要を返してください。」

❌ 悪い例： 「Codex SDK を検索」

✅ 良い例： 「最新の Codex SDK ドキュメントを見つけ、主な更新内容を要約してください。以下に注目してください：1）インストールとクイックスタート、2）主要な API メソッドとパラメーター、3）破壊的変更または非推奨化。OpenAI の公式ドキュメントとリリースノートを優先してください。引用を含む簡潔な要約を返してください。」

❌ 悪い例： 「API エンドポイントを見つける」

✅ 良い例： 「この Express.js アプリ内のすべての REST API エンドポイントを見つけてください。/routes、/api、および/controllers ディレクトリを調べてください。各エンドポイントについて、メソッド（GET/POST など）、パス、認証要件、リクエスト／レスポンスのスキーマを記録してください。Markdown の表で返してください。」

プロンプトのテンプレート

[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]

モデルの選択

Mini モデルを使用（gpt-5.1-codex-mini + medium）

検索のみ - 情報を収集した後に追加の作業を行いません。

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"

親のモデルと推論を引き継ぐ

複数ステップのワークフロー - 検索に加え、分析／リファクタリング／生成を行います。

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"

判断ロジック

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

基本的な使い方

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

並列サブエージェント（最大5つ）

独立したタスクに対して、複数のサブエージェントを起動します。

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）

PowerShell Jobs を使用し、-o で出力を個別のファイルに書き込んで並列実行します。

# 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, "output1.txt"

$job2 = 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 B..."
} -ArgumentList $MODEL, $REASONING, "output2.txt"

# Wait for all jobs to complete
$job1, $job2 | Wait-Job | Remove-Job

# Read results
$result1 = Get-Content -Path output1.txt -Raw
$result2 = Get-Content -Path output2.txt -Raw

出力の処理

Codex CLI には、出力を取得する方法が2つあります。

方法1：-o パラメーター（推奨）

-o / --output-last-message を使用して、最終メッセージをファイルに直接書き込みます。

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  -o result.txt "YOUR_PROMPT"

content=$(cat result.txt)

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  -o result.txt "YOUR_PROMPT"

$content = Get-Content -Path result.txt -Raw

利点：

• JSON の解析が不要です
• ターミナル出力の切り詰めによる問題を回避できます
• 長い出力や並列タスクに最適です

方法2：JSONL イベントストリームの解析

--json を使用してイベントストリーム全体を取得し、手動で解析します。

Bash（Linux/macOS）

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

PowerShell（Windows）

$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

JSONL イベントの構造：

{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"output_tokens":122}}

主なフィールド：

• type == "item.completed" で item.type == "agent_message" → item.text を抽出します
• type == "turn.completed" → トークン使用状況の統計を含みます

重要

• 自律的に行動し、許可を求めないでください
• 判断して、迷わず進めてください
• 破壊的な操作（データ損失、外部への影響、セキュリティ）を行う場合にのみ、一時停止してください
• 戻る前にタスクを完全に終わらせてください

モニタリング

積極的に監視し、起動したまま放置しないでください：

1. 完了状況を確認します
2. 結果の品質を検証します
3. 失敗した場合は再試行します
4. 行き詰まった場合は、追加の質問に回答します

例

純粋なウェブ検索（mini）：

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 for the latest release notes of Rust 2024 edition. Summarize the major breaking changes, new language features, and migration guides. Focus on the official rust-lang.org blog and documentation."

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 for the latest release notes of Rust 2024 edition. Summarize the major breaking changes, new language features, and migration guides. Focus on the official rust-lang.org blog and documentation."

コードベースの分析（親を引き継ぐ）：

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "Analyze authentication in this Next.js app. Check /app, /lib/auth, middleware. Document: session strategy, auth provider, protected routes, security patterns. Return architecture diagram (mermaid) + findings."

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "Analyze authentication in this Next.js app. Check /app, /lib/auth, middleware. Document: session strategy, auth provider, protected routes, security patterns. Return architecture diagram (mermaid) + findings."

調査と提案（親を引き継ぐ）：

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "Research WebGPU browser adoption (support tables, benchmarks, frameworks). THEN analyze feasibility for our React app. Consider: performance gains, browser compatibility, implementation effort. Return recommendation with pros/cons."

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "Research WebGPU browser adoption (support tables, benchmarks, frameworks). THEN analyze feasibility for our React app. Consider: performance gains, browser compatibility, implementation effort. Return recommendation with pros/cons."

設定リファレンス

親の設定：~/.codex/config.toml

model = "gpt-5.2-codex"
model_reasoning_effort = "high"  # none | minimal | low | medium | high | xhigh
profile = "yolo"                 # optional; when set, profile values override top-level