codex-research

Codex Research

Web research via the codex plugin companion script, synthesized by Claude Code.

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. Run /codex:setup first." and fall back to Claude Code research.

Usage for research tasks:

node "$CODEX_COMPANION" task "<research prompt>"

The task command runs Codex in read-only mode by default (no --write flag), which is appropriate for research.

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), skip all codex steps and jump directly to the Fallback step. Do NOT report the rate limit to the user — silently fall back.

Step 1: Understand the Research Topic

Clarify what needs to be researched:

• Specific question or topic
• Scope and depth needed
• How findings will be used

Step 2: Build Research Prompt

Craft a focused prompt:

Research the following topic: <topic>

Specific questions to answer:
1. <question 1>
2. <question 2>
3. <question 3>

Provide:
- Key findings with sources/URLs where possible
- Comparison of alternatives if applicable
- Concrete recommendations based on findings
- Code examples if relevant

Be thorough but concise. Cite sources.

Step 3: Run Codex

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

${TIMEOUT_CMD:+$TIMEOUT_CMD} ${TIMEOUT_CMD:+1500} node "$CODEX_COMPANION" task \
  "<research prompt>" \
  > "$LOGDIR/${DATETIME}-codex-research-{topic-slug}.md" \
  2>"$LOGDIR/${DATETIME}-codex-research-{topic-slug}-stderr.log"

Timeout: 25 minutes.

Step 4: Check for Rate Limiting

After codex completes (or times out), check output files for rate limit errors:

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

If exit code is non-zero (rate limit detected), jump to Fallback.

Step 5: Fallback — Opus

If codex times out, produces no output, or is rate-limited:

• Silently fall back to Opus — do NOT report the rate limit or timeout to the user. Do NOT pause the workflow.
• Spawn a researcher subagent with model: opus to perform the research via Claude Code tools (WebSearch, WebFetch, etc.). Opus is the designated Claude-side stand-in for codex throughout these skills.
• Continue the workflow as if the researcher subagent was the original plan

Step 6: Synthesize

1. Read codex output from the log file
2. Verify key claims where possible
3. Organize findings into a clear structure
4. Present to the user with source references

Step 7: Save Research Log

Save the final synthesized findings:

node $HOME/.claude/scripts/save-file.js "{logdir}/{timestamp}-research-{topic}.md" "<content>"

Then format:

pnpm dlx @takazudo/mdx-formatter --write <file>

Timeout Policy

• Timeout: 25 minutes (1500s)
• If codex times out: Silently fall back to Opus (researcher subagent at model: opus)
• Research is read-only — codex cannot modify files

Important Notes

• Codex can do web research natively
• All file writing done by Claude Code, never by codex
• Long timeout (25 min) to give research room to complete
• Falls back to a researcher subagent at model: opus if codex fails
• Silent fallback policy: If codex is rate-limited, timed out, or unavailable, silently fall back to the researcher subagent at model: opus. NEVER pause the workflow, NEVER report the rate limit to the user, NEVER ask what to do. Opus is the designated Claude-side stand-in for codex throughout these skills
• NEVER use ~ in paths — use $HOME