codex-research

Codex Research + Cross-Model Synthesis

Use Codex for deep-dive research via the companion task subcommand. Claude evaluates, verifies claims, fills gaps, and synthesizes a combined analysis.

Step 1: Pre-flight — Companion Check

Before any file reading or prompt building, verify companion availability:

CODEX_COMPANION=$("${CLAUDE_PLUGIN_ROOT}/scripts/resolve-companion.sh")

If resolve fails: direct to /codex-setup immediately. Do NOT proceed to read files or build prompts. Do NOT fall back to a Claude-only solo analysis.

Step 2: Determine Research Task

Parse $ARGUMENTS:

Input	Action
A question or topic	Research directly
Path to a file	Read file, use as context
resume [follow-up]	Pass --resume-last "[follow-up]" to companion task
(no args)	Ask user: "What should I research?"

Step 3: Build Research Prompt

Read ${CLAUDE_PLUGIN_ROOT}/references/gpt-prompting.md for XML tag structure.

Adapt <task> to context:

• Issue investigation → "root cause analysis, reproduction steps"
• Technology comparison → "trade-offs, real-world adoption, gotchas"
• Architecture → "patterns, anti-patterns, scale"
• General → "breadth first, then depth on interesting findings"

Write to ${CLAUDE_PLUGIN_DATA}/tmp/codex-research-prompt.txt.

Compose the prompt by assembling these XML blocks. Replace placeholder values with actual content. Include the <context_document> block only if the user provided a document.

<task>
You are a technical researcher conducting a deep investigation.
Topic: [INSERT USER QUESTION OR TOPIC]
[If document provided: "Context document is provided below."]
Investigate thoroughly. Use web search if helpful.
Surface non-obvious insights, not just the first answer.
</task>

<compact_output_contract>
Structured analysis with clear sections.
Separate: observed facts, reasoned inferences, open questions.
Identify risks, trade-offs, alternative perspectives.
</compact_output_contract>

<research_mode>
Breadth first, then depth where evidence changes the recommendation.
</research_mode>

<citation_rules>
Cite sources. Prefer primary. Say "I'm not sure" rather than guessing.
</citation_rules>

<grounding_rules>
Ground claims in evidence. Label hypotheses clearly.
</grounding_rules>

[Only if document provided:]
<context_document>
[INSERT DOCUMENT CONTENT]
</context_document>

Create directory if needed: mkdir -p ${CLAUDE_PLUGIN_DATA}/tmp

Step 4: Execute via Companion Script

Use the $CODEX_COMPANION resolved in Step 1:

node "$CODEX_COMPANION" task --prompt-file "${CLAUDE_PLUGIN_DATA}/tmp/codex-research-prompt.txt"

Timeout: 300000ms (5 minutes). Job is tracked and visible in /codex:status.

Step 5: Double-Check & Synthesize

Read ${CLAUDE_PLUGIN_ROOT}/references/evaluation.md.

1. Verify claims — Check facts against own knowledge. Flag fabrications.
2. Fill gaps — Add perspectives Codex missed.
3. Challenge assumptions — Call out unstated assumptions.
4. Synthesize — Combine findings into coherent analysis.

Adapt output format to question:

• Comparison → table
• Pros/cons → list
• Root cause → chain
• Survey → categorized bullets

Step 6: Save & Clean Up

Save to ${CLAUDE_PLUGIN_DATA}/reviews/research-<YYYYMMDD-HHMMSS>.md:

# Codex Research — <date>

## Topic
<what was investigated>

## Codex Findings
<verbatim>

## Claude's Evaluation & Synthesis
<independent analysis>

## Agreement: <High|Partial|Disagreement>

## Key Takeaways
- <actionable conclusions>

rm -f ${CLAUDE_PLUGIN_DATA}/tmp/codex-research-prompt.txt

Gotchas

• Codex can hallucinate sources and facts. Verify specific claims.
• Value is in synthesis. If Claude reaches same conclusion alone, Codex added nothing.
• Do not auto-fix. Present findings, wait for user.
• Resume supported. User can /codex-research resume [follow-up] — pass --resume-last to companion.