Codex 2nd

Codex 2nd Opinion

Get a second opinion from the codex plugin companion script on a plan, approach, or codebase exploration. Codex reads workspace files and does web research to provide an independent perspective.

Codex Plugin Companion Script

The codex plugin provides a companion script for running tasks. Resolve it dynamically:

CODEX_PLUGIN_ROOT=$(command ls -d "$HOME/.claude/plugins/cache/openai-codex/codex"/*/ 2>/dev/null | sort -V | tail -1)
CODEX_COMPANION="${CODEX_PLUGIN_ROOT}scripts/codex-companion.mjs"

If the file does not exist, report "Codex plugin not installed — skipping second opinion" and continue without it.

Usage for second opinion tasks:

node "$CODEX_COMPANION" task "<prompt>"

The task command runs Codex in read-only mode by default (no --write flag).

Process

Step 0: Pre-flight Rate Limit Check

Before doing anything, check if Codex is currently rate-limited:

RATE_CHECK=$(node $HOME/.claude/scripts/codex-rate-limit.js check 2>&1)
RATE_EXIT=$?

If RATE_EXIT is non-zero (rate-limited), silently fall back to Opus (see Step 5 Fallback). Do NOT report the rate limit to the user or pause the workflow.

Step 1: Build Context Prompt

Construct a prompt that includes:

• The current plan or approach being considered
• Key files or areas of the codebase involved
• Specific questions or concerns to address

You are reviewing a development plan. Provide a second opinion.

## Context
<what the project is, what repo we're in>

## Current Plan
<the plan or approach being considered>

## Questions
1. Are there any risks, edge cases, or issues with this approach?
2. Is there a simpler or better alternative?
3. Are there any files or areas of the codebase that should be considered but aren't mentioned?
4. Any other suggestions or concerns?

Be concise and practical. Focus on actionable feedback. If the plan looks solid, say so briefly — don't invent problems.

Step 2: Run Codex

MUST run in the background. Call the Bash tool with run_in_background: true. The Bash tool's foreground timeout is capped at 600000 ms (10 minutes) — a larger timeout argument is silently clamped, so a foreground run is SIGKILLed at 10 minutes no matter what gtimeout is set to, leaving a 0-byte output file and an orphaned codex-companion.mjs process. Backgrounded commands are not subject to that cap.

After launching, wait for the task-completion notification (or poll the output file), then continue at Step 3. If a foreground run was started by mistake and got killed, clean up the orphan before retrying: pkill -f 'codex-companion.mjs'

LOGDIR=$(node $HOME/.claude/scripts/get-logdir.js)
mkdir -p "$LOGDIR"
DATETIME=$(date +%Y%m%d_%H%M%S)

# Resolve codex companion script
CODEX_PLUGIN_ROOT=$(command ls -d "$HOME/.claude/plugins/cache/openai-codex/codex"/*/ 2>/dev/null | sort -V | tail -1)
CODEX_COMPANION="${CODEX_PLUGIN_ROOT}scripts/codex-companion.mjs"

# Detect timeout command (gtimeout on macOS via coreutils, timeout on Linux/WSL)
if command -v gtimeout &>/dev/null; then
  TIMEOUT_CMD="gtimeout"
elif command -v timeout &>/dev/null; then
  TIMEOUT_CMD="timeout"
else
  TIMEOUT_CMD=""
  echo "WARNING: neither gtimeout nor timeout found. Running without timeout."
fi

bash $HOME/.claude/scripts/codex-guard.sh --wait 300 -- \
  ${TIMEOUT_CMD:+$TIMEOUT_CMD} ${TIMEOUT_CMD:+1800} node "$CODEX_COMPANION" task \
  "<prompt>" \
  > "$LOGDIR/${DATETIME}-codex-2nd.md" \
  2>"$LOGDIR/${DATETIME}-codex-2nd-stderr.log"

Long prompts: write the prompt to a file first and pass it as PROMPT=$(cat <prompt-file>) … task "$PROMPT", rather than inlining a multi-hundred-line heredoc into the command.

Timeout: 30 minutes (1800s), enforced by gtimeout/timeout inside a backgrounded Bash call.

Step 3: Collect Results

1. Check for rate limiting in output files:

   node $HOME/.claude/scripts/codex-rate-limit.js check-output \
     "$LOGDIR/${DATETIME}-codex-2nd.md" \
     "$LOGDIR/${DATETIME}-codex-2nd-stderr.log"
   

   If rate limit detected, jump to Step 5 Fallback (Opus second opinion).

2. Read the output file

3. If empty or missing, check stderr log for errors

4. If codex timed out or failed, jump to Step 5 Fallback

Step 4: Return Feedback

Return the codex feedback to the caller. The caller decides whether to incorporate it into the plan.

Step 5: Fallback — Opus second opinion

If codex was rate-limited, timed out, or produced no usable output, silently fall back to Opus. Spawn one general-purpose subagent with model: opus to give the same second opinion the codex prompt would have produced. The caller still gets advisory feedback — no quota-loud failure mode, no missing second opinion.

Agent tool:
  description: "Opus 2nd opinion (codex fallback)"
  subagent_type: "general-purpose"
  model: "opus"
  prompt: <same second-opinion prompt that would have gone to codex — plan/context + the standard questions>

Return the subagent's feedback to the caller exactly as if it came from codex. Do NOT mention the fallback to the user — silent means silent.

Timeout Policy

• Timeout: 30 minutes (1800s), via gtimeout/timeout
• MUST be backgrounded (Bash run_in_background: true). The Bash tool clamps foreground timeout to 600000 ms, so any foreground run dies at 10 minutes with a 0-byte output file and an orphaned codex-companion.mjs
• If codex times out: Silently fall back to Opus (Step 5)
• Fallback agent: general-purpose subagent at model: opus — the caller always gets a second opinion, just from Opus instead of codex when codex is down. Opus is the designated Claude-side stand-in for codex throughout these skills

When Called by /x-as-pr or /x-wt-teams

These skills call /codex-2nd during their planning phase:

1. After understanding the task and forming an initial plan
2. Send the plan to codex for feedback
3. If useful feedback is returned, update the plan
4. Optionally re-run /codex-2nd with the updated plan (up to 3 iterations total)
5. Finalize the plan and proceed with implementation

Important Notes

• Codex reads workspace files for context — no need to paste file contents into the prompt
• All file writing done by Claude Code, never by codex
• This is advisory — never block the workflow if codex is unresponsive
• Silent fallback policy: If codex is rate-limited, timed out, or unavailable, silently fall back to an Opus general-purpose subagent (Step 5). NEVER pause the workflow, NEVER report the rate limit, NEVER ask what to do. The caller still gets a second opinion — just from Opus instead of codex
• NEVER use ~ in paths — use $HOME