codex

name

codex

description

codex（OpenAI のコーディングエージェント）に codex CLI 経由で相談するスキル。第二意見・別アプローチ・難所のレビューを codex に求めるときに使う。CLI の実行と完走管理は codex-runner サブエージェントが担い、メイン Claude は codex-runner を background で起動して即座に別作業へ移る（何時間かかってもブロックされない）。タスクの重さに応じて reasoning effort と model（GPT-5.6 系）を毎回明示的に選び（既定任せにしない）、相談・レビューは sandbox=read-only。「codexに聞いて」「codexの意見」「codexに相談」「codexならどうする」「ask codex」「second opinion from codex」などで起動する。Claude 自身がタスク途中で codex に相談すると判断したときも、本スキルの手順が SSOT になる。ユーザーが /codex と入力したら必ずこのスキルを使う。

/codex — codex への相談（codex-runner 経由）

/codex <相談内容> で codex に第二意見を求める。Claude がタスク途中で「codex にも聞こう」と判断したときも本スキルの手順に従う（これが codex 相談の SSOT）。

ℹ️ codex は MCP を廃止し、codex CLI（codex exec / codex exec resume）に全面移行済み。mcp__codex__codex は使わない。

アーキテクチャ

CLI 実行と完走管理は codex-runner サブエージェントが担う。メイン Claude は run_in_background: true で起動して即座に別作業へ移る。

メイン Claude : Agent(subagent_type: "codex-runner", run_in_background: true)
                → 即座に自由。他の作業を続ける / ターンを終える
codex-runner  : codex exec を nohup でデタッチ起動
                → 自分のターン内で完了マーカーが出るまで foreground ポーリング
                → 600 秒で切れたら同じポーリングを叩き直す（最大 20 ラウンド ≒ 3 時間）
                → 結果を確定して報告し終了
メイン Claude : codex-runner の完了通知で起こされ、結果を受け取る

⚠️ codex 本体は run_in_background で起動しない（nohup でデタッチする）。 対照実験（2026-08-02）で、同一コマンドを 2 系統同時に走らせたところ run_in_background 側は約 52 分で kill、nohup 側は生存継続した。別の実行では 60 分で殺されており上限は固定値ではない。max effort の長尺ジョブは実測で 44〜48 分かかるため上限に触れうる。Agent 自体を run_in_background: true で起動するのはこの制約とは別で、従来どおり行う。

この分業の要点: ブロックする主体を codex-runner に隔離する。codex が何分走ろうとメイン Claude は止まらない。

⚠️ メイン Claude が自分で foreground ポーリングしてはならない。 メインのターンが待機時間ぶん丸ごと停止し、この設計の意味が消える。長時間ジョブを foreground で抱えるのは codex-runner の仕事。

なぜ codex-runner に background 完了通知を待たせないのか

background Bash の完了通知自体はサブエージェントにも届く（2026-08-01 実測）。しかしサブエージェントはツール呼び出しを出さずにテキストを返した時点でターンが終了するため、「何もせず通知を待つ」状態が構造的に存在しない。だから待ち方はポーリング一択になる。

2026-07-15〜07-21 に 5 回連続で失敗したのは、この点を取り違えて「通知を待ちます」と返る実装になっていたため（および 07-16 版でリトライ分岐を複雑にしすぎて途中で諦めていたため）。現行の codex-runner はポーリング条件を完了マーカーファイルの出現ひとつに固定し、分岐を持たない。

呼び出し手順

1. codex-runner を background 起動する

Agent({ subagent_type: "codex-runner", run_in_background: true, ... }) で起動し、プロンプトに以下を渡す:

名前	内容
PROMPT	相談内容（背景・前提・聞きたい論点を具体的に）
CWD	codex の作業ディレクトリ（対象リポの絶対パス）
SANDBOX	相談・レビューは read-only。実装を任せる場合のみ workspace-write
MODEL / EFFORT	毎回タスクの重さから明示的に選んで渡す（下記ルブリック。省略・既定任せにしない）
WORK_DIR	入出力ファイルの置き場（スクラッチパス等）
RUN_ID	この実行を一意に識別する文字列。並列起動時は必ず別々の値にする
SESSION_FILE	任意。会話を継続したいとき用の thread_id 永続化ファイルパス

2. 待たずに別作業へ移る

メイン Claude はブロックされない。他の作業を続けるか、やることが無ければターンを終える。codex-runner の完了通知で起こされる。

3. 結果を受け取る

codex-runner は EXIT / thread_id / 応答本文 / エラー / ポーリング総ラウンド数を報告する。実データのみを根拠にユーザーへ報告する（捏造禁止）。

4. 会話の継続（resume）

続き質問は、同じ SESSION_FILE を渡して新しい codex-runner を起動する。codex-runner が codex exec resume <thread_id> で同一 thread に会話を積む。前の codex-runner インスタンスが生きていれば SendMessage で継続してもよい。

effort 選択ルブリック

EFFORT（= model_reasoning_effort）は毎回タスクの重さから選ぶ（固定既定に流さない）:

effort	場面
low	ごく軽い事実確認・大量の軽い確認（下げるのはこの用途だけ）
medium	軽い確認・小差分レビュー・事実寄りの質問
high	非自明なデバッグ・複数ファイル設計レビュー・トレードオフ判断
xhigh	難しい根本原因究明・複雑アルゴリズム/設計・詰まった時の深掘り
max / ultra	最難関（gpt-5.6-sol / -terra のみ対応。滅多に使わない）

model の選択

MODEL は毎回 GPT-5.6 系から選ぶ（既定任せにしない）。codex debug models で最新一覧を確認できる。

model	モデル既定 effort	対応 effort
gpt-5.6-sol	low	low / medium / high / xhigh / max / ultra
gpt-5.6-terra	medium	low / medium / high / xhigh / max / ultra
gpt-5.6-luna	medium	low / medium / high / xhigh / max

明示オーバーライド

• /codex --effort xhigh <相談> — effort を固定
• /codex --model gpt-5.6-terra <相談> — model を明示指定（GPT-5.6 系から選ぶ）

注意

• 相談・レビュー用途は必ず SANDBOX=read-only。config.toml の既定は workspace-write（codex がリポを書ける）なので、明示的に read-only を渡す。実装を任せる時だけ workspace-write
• codex の自己申告を鵜呑みにしない。「実装した / テスト通した」等は、git 等で実体検証してから採用する
• 応答待ちの間にメイン Claude の作業を止めない。結果は返ってきた実データのみで報告し、待ち時間に予測で答えを書かない
• MCP（mcp__codex__codex 系）は廃止済み。必ず CLI 経由