codex-subagent

Codex CLI をサブエージェントとして使う

Codex CLI は OpenAI のターミナル向けコーディングエージェントです。codex exec は非対話モードで実行します。 サンドボックス内で自律的に動作し、進行状況を stderr にストリーミングし、最終メッセージのみを stdout に出力します。認証にはユーザーの ChatGPT サブスクリプションを再利用し、API キーは使用しません。

委任するタイミング

• 成功条件が明確で、自己完結したコーディングタスク（修正、機能追加、リファクタリング、レビュー）。
• 並行作業：複数の独立したタスクを一度に実行する場合（「並列実行」を参照）。
• セカンドオピニオン／自分の変更の独立した検証。

プロンプトに完全に書き込めない会話のコンテキストが必要なタスクは委任しないでください。

事前確認

codex --version       # missing? npm i -g @openai/codex  (or: brew install --cask codex)
codex login status    # exit 0 + "Logged in using ChatGPT" = ready

ログインしていない場合 → 停止し、ユーザーに codex login を実行するよう伝えます（初回のみブラウザーで OAuth 認証を行います）。 認証情報（~/.codex/auth.json）を読み取ったり、表示したり、コピーしたりしないでください。

起動

OUT=$(mktemp /tmp/codex-out.XXXXXX)
codex exec \
  --cd /path/to/repo \
  --model gpt-5.6-sol \
  --config model_reasoning_effort=high \
  --sandbox workspace-write \
  --output-last-message "$OUT" \
  "Full task prompt: goal, constraints, files to touch, definition of done." \
  </dev/null

• 常に GPT 5.6 Sol（gpt-5.6-sol）を使用します。推論の強度はデフォルトで high にします。 新しい Codex の実行ごとに、両方のフラグを明示的に渡してください。
• Codex の高速モードは使用しないでください。
• stdin が実際の端末ではない場合（バックグラウンドシェル、スクリプト）には、</dev/null が必須です。codex は開いたままの stdin を追加コンテキストとして扱い、EOF を待ち続けます。
• Codex は会話の内容を一切認識しません。目的、関連するパス、制約、完了の確認方法など、すべてのコンテキストをプロンプトに記載してください。
• プロンプトが長い場合は、代わりに stdin 経由で渡します：codex exec [flags] - < /tmp/task.md。
• ホストエージェントにバックグラウンド/Bash サブエージェントがある場合は、それでコマンドをラップします（Cursor：シェルサブエージェントを使う Task ツール）。こうすると、Codex の冗長な出力が親コンテキストに入らずに済みます。利用できない場合は、通常のバックグラウンドターミナルを使います。
• 実行には数分かかり、組み込みのタイムアウトはありません。バックグラウンドで実行し、監視してください。
• オプション：JSONL イベントストリームには --json を使います。

結果の取得

cat "$OUT"                            # final message = the deliverable
git -C /path/to/repo status --short   # see what Codex actually changed

同じセッションで続行する場合（同じ cwd から実行してください。resume は cwd で絞り込みます）：

codex exec resume --last "follow-up instruction" </dev/null

並列実行

本当に独立したタスクのみを並列化し、結果をきれいにマージできるよう、あらかじめファイルの担当範囲を割り当ててください。Codex の実行ごとに Git worktree を 1 つ使います。同じツリー内で 2 つ実行しないでください。

git worktree add /tmp/wt-taskA -b codex/task-a
codex exec --cd /tmp/wt-taskA --model gpt-5.6-sol \
  --config model_reasoning_effort=high --sandbox workspace-write \
  -o /tmp/outA.md "task A" </dev/null

失敗時の対応

• 出力がないまま永久に停止する → stdin が開いたままです。停止し、</dev/null を付けて再起動します。
• codex login status がゼロ以外を返す → ユーザーが codex login を実行する必要があります。回避しないでください。
• ChatGPT プランのレート制限に達した → ユーザーに報告し、ループで再試行しないでください。
• 「Not a git repo」エラー → --skip-git-repo-check を追加するか、先にリポジトリを初期化してください。
• デフォルトでは、workspace-write サンドボックス内ではネットワークがブロックされています。タスクでネットワークが必要な場合（インストール、API 呼び出し）は、-c sandbox_workspace_write.network_access=true を指定してください。
• --dangerously-bypass-approvals-and-sandbox は絶対に使用しないでください。

ルール

• 起動ごとにタスクは 1 つにします。大きな作業は複数回に分けて起動してください。
• タスク完了を宣言する前に、Codex の差分を自分で確認してください。

Cursor ネイティブのラッパー（任意）

Cursor 内で自動ルーティングし、/codex を呼び出すには、~/.cursor/agents/codex.md を追加します。 説明が「Codex CLI にコーディングタスクを委任します」で、本文がこのスキルを参照するカスタムサブエージェントです。