Pev Bootstrap Codex

pev-bootstrap-codex

/pev-init --codex で呼ばれる one-time setup skill。 v2.0 で導入された pev-external-reviewer skill と v3.5.0 で導入された pev-external-executor skill を使えるようにする preflight setup。 v1.4 で確立した pev-bootstrap-playwright pattern を external reviewer / executor に拡張した sibling。 codex CLI の install / 認証は reviewer と executor で共通のため、 本 skill 1 つで両方を setup する。

When to Use

起動すべき場面:

• /pev-init --codex が user に呼ばれた時
• pev-external-reviewer / pev-external-executor skill の Preflight で「codex CLI 未setup」 を検知した時 (auto-propose)
• PEV_REVIEWER_MODE=dual-codex|codex-only (v2.0+) または PEV_EXECUTOR_MODE=codex (v3.5.0+) を有効化したい時

起動すべきでない場面:

• codex CLI が既に install 済 + CODEX_API_KEY 設定済 + sanity test pass の場合 (Preflight が detect、 idempotent skip)
• 外部 model を使わない方針のチーム (PEV_REVIEWER_MODE=claude-only で固定する場合)

CLI flags

• --dry-run: 「実行予定 + 検知結果」 を stdout に full block で出力、 実 install は行わない
• --force: idempotent skip も bypass、 既存 install 済でも sanity test を再実行

Bootstrap Steps

Step 1: Preflight check

codex CLI は 2 種類の認証方式 をサポート (どちらか 1 つで OK):

• (a) ChatGPT subscription auth (default、 推奨): codex login で ChatGPT account に sign-in 済の状態。 ChatGPT Plus / Pro / Team / Enterprise の subscription が必要、 API call cost は別途発生せず subscription 内で消費
• (b) API key auth: OPENAI_API_KEY 環境変数 (v0.128+) または CODEX_API_KEY (v0.130+ docs)。 printenv OPENAI_API_KEY | codex login --with-api-key で codex に教える

# codex CLI 存在確認 + version
CODEX_BIN=${PEV_CODEX_BIN:-codex}
if command -v "$CODEX_BIN" >/dev/null 2>&1; then
  CODEX_VERSION=$("$CODEX_BIN" --version 2>/dev/null || echo unknown)
  CODEX_INSTALLED=true
else
  CODEX_INSTALLED=false
fi

# 認証状態確認 (subscription / API key どちらかが effective なら OK)
AUTH_STATUS=$("$CODEX_BIN" login status 2>/dev/null || echo "Not logged in")
case "$AUTH_STATUS" in
  *"Logged in using ChatGPT"*)
    AUTH_MODE="subscription"; AUTHENTICATED=true ;;
  *"Logged in using API key"*|*"Logged in"*)
    AUTH_MODE="api_key"; AUTHENTICATED=true ;;
  *)
    AUTH_MODE="none"; AUTHENTICATED=false ;;
esac

idempotent: CODEX_INSTALLED=true かつ AUTHENTICATED=true かつ Step 4 sanity test pass なら early exit + 「既に setup 済 (auth: $AUTH_MODE)」 message。 --force 時のみ bypass。

Step 2: codex CLI install

CODEX_INSTALLED=false の場合のみ。 install path 自動検知 (上から優先):

skill は user に AskUserQuestion で「どの install method?」 を確認 (--force 時は brew → npm → manual の順で auto-try、 全部 fail なら hard error)。

install 後、 Step 1 を再実行して CODEX_INSTALLED=true を再確認。

Step 3: 認証設定確認

AUTHENTICATED=false の場合、 user に AskUserQuestion で 3 択を提示:

Q: codex CLI が未認証です。 どちらで認証しますか?
- (a) ChatGPT subscription (推奨、 ChatGPT Plus / Pro / Team / Enterprise の login):
      `codex login` を別 terminal で実行、 ブラウザで ChatGPT に sign-in
- (b) API key (CI / 自動化向け):
      `printenv OPENAI_API_KEY | codex login --with-api-key` で codex に取り込み。
      OPENAI_API_KEY env var は shell rc / direnv に永続化
- (c) 後で自分で設定する:
      skill は sanity test を skip、 user が後で `codex login` を実行

skill 自身は API key 値を読まない / 書かない (security の理由、 user が rc に書く形を推奨)。 subscription auth path では env var すら不要。

API key 認証時の env var 名:

• OPENAI_API_KEY (codex CLI v0.128+ の login help が言及、 dog food で実証済)
• CODEX_API_KEY (v0.130+ の public docs が言及)

skill は先に OPENAI_API_KEY をチェックし、 不在なら CODEX_API_KEY を試す。 両方不在ならまだ未認証。 codex CLI の version によってどちらが effective かが変わるため、 user 環境に合わせて auto-detect する。

Step 4: Sanity test

CODEX_INSTALLED=true かつ AUTHENTICATED=true なら以下を実行:

# git repo 外でも動くよう --skip-git-repo-check、 session を残さないよう --ephemeral
RESULT=$(timeout 60 codex exec --json --skip-git-repo-check --ephemeral \
  --sandbox workspace-write \
  "Reply with the single word 'pong'" 2>&1)
echo "$RESULT" | tail -5

期待: JSONL の中に "item.message_content" のような final assistant message があり、 内容が "pong" 系の短文。 timeout / non-zero exit / 認証 error の場合は warning + 「codex login status で認証状態を確認してください」 hint。

Step 5: settings.local.json 雛形提案

AskUserQuestion で multi-select。 codex は Reviewer (Verify phase) と Executor (Execute phase) の両方で使えるため、 両方の default を 1 回で決める:

Q: codex を pev-harness のどこで使う default にしますか? (.claude/settings.local.json に書く)
- [ ] PEV_REVIEWER_MODE=dual-codex   (--strict 時 A=claude-opus + B=codex で verify)
- [ ] PEV_REVIEWER_MODE=codex-only   (codex 単独 verifier、 cost 削減)
- [ ] PEV_EXECUTOR_MODE=codex        (Execute phase の実 file 編集を codex に委譲、 v3.5.0+)
- [ ] 設定しない (毎回 CLI flag で指定)

選択された値を .claude/settings.local.json の env に書き込み (既存があれば merge)。 PEV_REVIEWER_MODE と PEV_EXECUTOR_MODE は独立した設定で、 両方選択しても良い (codex で実装して codex で review、 という構成も可能)。

Step 6: Result summary

通常モードで以下を assistant 最終応答テキスト = stdout に full block で出力 (v1.9 dog food finding F1 と同方針):

[pev-init --codex] complete

Detected:
  codex CLI:   0.130.0 (installed via brew)
  auth mode:   subscription (Logged in using ChatGPT)
  sanity test: PASS (latency: 2.3s)

Configured:
  .claude/settings.local.json: env.PEV_REVIEWER_MODE = dual-codex
  .claude/settings.local.json: env.PEV_EXECUTOR_MODE = codex

Next steps (reviewer):
  1. /pev "Your task" --reviewer-mode=dual-codex   # 1回試す
  2. /pev "Your task" --strict                     # PEV_REVIEWER_MODE が dual-codex なので codex も走る
  3. verify.json.reviewers[] で codex 結果を確認

Next steps (executor, v3.5.0+):
  1. /pev "Your task" --executor-mode=codex        # 実装を codex に委譲して 1 回試す
  2. execute.log の [Executor: codex] block で結果を確認

Fallback behavior:
  codex CLI が runtime に fail した場合、 reviewer は自動で dual-claude に degrade (verify.json.fallback_reason)、
  executor は自動で Claude native 実装に degrade (execute.log の fallback_reason)

--dry-run 時は実 install / 書き込み行わず予定のみ出力。

Security considerations

• skill 自身は API key の値を read しない、 値 setting は user が rc / direnv / codex login --with-api-key で行う
• subscription auth path では API key 不要、 codex 内部 (~/.codex/) に session token が保存される (codex CLI が管理)
• sanity test の output は最終 message のみ表示、 full JSONL stream は表示しない (API レスポンスの誤含有 PII を minimize)
• .claude/settings.local.json は user-local (gitignore 推奨)、 settings.json (team 共有) には書かない

Examples

macOS で初回 setup (subscription auth、 推奨)

brew install --cask codex
codex login           # ブラウザで ChatGPT に sign-in
codex login status    # "Logged in using ChatGPT" を確認
claude --plugin-dir ~/pev-harness --print '/pev-harness:pev-init --codex'

CI 用 (API key auth)

brew install --cask codex
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status    # "Logged in using API key" を確認
claude --plugin-dir ~/pev-harness --print '/pev-harness:pev-init --codex --force'

dry-run で内容確認

claude --plugin-dir ~/pev-harness --print '/pev-harness:pev-init --codex --dry-run'

→ install / 書き込み行わず、 「現状 + 予定」 だけ出力。

CI / 自動化 (--force + API key auth)

export OPENAI_API_KEY=$SECRET_OPENAI_KEY
printenv OPENAI_API_KEY | codex login --with-api-key
claude --plugin-dir ~/pev-harness --print '/pev-harness:pev-init --codex --force'

→ interactive prompts skip + install method auto-try + sanity test 必ず実行。

Related

• pev-external-reviewer — v2.0 codex を Reviewer として呼ぶ skill (本 skill が setup する対象)
• pev-external-executor — v3.5.0 codex を Executor として呼ぶ skill (本 skill が setup する対象)
• pev-bootstrap-playwright — v1.4 sibling (E2E 専用)
• pev-bootstrap-project — v1.9 sibling (project 全体)
• commands/pev-init --codex.md — 本 skill の薄い CLI ラッパー
• Codex CLI 公式 docs: https://developers.openai.com/codex/noninteractive

Notes

• skill は idempotent に設計: 同じ環境で何度 invoke しても install 済なら no-op (Preflight が早期 exit)
• --force は user の明示的 override channel、 skill 自身が判断して付与してはならない
• codex CLI 自身に timeout flag なし → wrap 側で timeout command を使う方針を pev-external-reviewer / verifier に統一
• 認証は 2 path: (a) ChatGPT subscription auth (推奨、 codex login でブラウザ sign-in)、 (b) API key auth (OPENAI_API_KEY env var を stdin で渡す codex login --with-api-key)。 codex v0.128 dog food で subscription auth が default として実証済。 CODEX_API_KEY は public docs で言及されているが v0.128 の help では OPENAI_API_KEY 表記のため両方確認