Claude codex research skill

codex-research

Deep research where Codex (gpt-5.5) does the searching, not Claude. Claude is the orchestrator: it splits the question, dispatches parallel research agents, and stitches their cited findings into one report. Each research agent is a cheap Sonnet-low subagent whose only job is to run the research engine — the codex exec CLI with live web search.

Roles (fixed):

• Orchestrator — Opus, high effort. The agent running this skill. Decomposes, dispatches, verifies, synthesizes. Does no web searching itself.
• Research agents — Sonnet, low effort. One per sub-question. Each shells out to codex-research.sh (which runs codex exec -m gpt-5.5 + web search) and returns the cited result. Cheap wrappers around Codex — they don't reason, they relay.

The engine is the driver script; the orchestration is Claude subagents. Both are proven working in this environment (see Gotchas for what took getting right).

Paths below are relative to this skill dir: ~/.claude/skills/codex-research/. The driver is codex-research.sh.

Two ways to run

Mode	Command / driver	Who orchestrates	Use when
Multi-agent (best quality)	Opus dispatches Sonnet-low Agents that each run codex-research.sh	Claude (Opus) decomposes, cross-checks, synthesizes	You want Claude's judgement in the loop; nuanced or high-stakes questions.
One-shot (convenience)	research-run.sh "question"	Codex does decompose + synthesize; bash fans out	You want a single command and a cited report with no babysitting.

Both share the same engine (codex-research.sh) and the same adversarial verification round (codex-verify.sh). Pick multi-agent when quality matters more than convenience; the one-shot trades Claude's cross-checking for a single command.

---

Prerequisites

• codex CLI on PATH (codex --version; developed against codex-cli 0.143.0).
• Codex authenticated: ~/.codex/auth.json exists and ~/.codex/config.toml trusts your home/working dir (trust_level = "trusted"). If auth lapses: codex login (interactive — ask the user to run ! codex login).
• python3 (used by the driver to extract the web-search trace).
• Network access for live search.

No repo, no build. Codex runs -s read-only --skip-git-repo-check --ephemeral in a throwaway workdir.

---

Run (agent path) — the engine, one sub-question at a time

A research agent runs exactly this, and nothing else:

~/.claude/skills/codex-research/codex-research.sh \
  --out /tmp/claude-1000/.../research/<slug>.json \
  --schema ~/.claude/skills/codex-research/findings.schema.json \
  --timeout 600 \
  "RESEARCH SUB-QUESTION. Use web search. Cite every claim with a source URL."

• Structured mode (--schema) → the --out file is JSON validated against findings.schema.json (subtopic, answer, key_facts[], sources[], confidence, gaps). Use this for fan-out so results merge cleanly.
• Markdown mode (drop --schema) → --out is a cited prose answer. Use for a single free-form question.
• The driver writes a JSONL event log to <out>.jsonl and prints the actual web searches Codex ran to stderr — grounding proof. Exit: 0 ok, 2 usage, 124 timeout, other = codex error.
• Depth knob: add --effort minimal|low|medium|high to raise Codex reasoning depth on a hard sub-question (maps to -c model_reasoning_effort). Omit for the Codex default. codex-verify.sh takes the same flag.

Verified live in this container (both modes returned correct, current, cited answers): Prisma 7.8.0 + MySQL 8.4 support, Next.js 16 stable, Python 3.14.

Direct invocation (test the engine without an agent)

~/.claude/skills/codex-research/codex-research.sh --out /tmp/x.md \
  "What is the newest Node.js LTS as of mid-2026? Use web search. 2 sentences, 1 URL."
cat /tmp/x.md

---

Run (one-shot pipeline)

research-run.sh runs the whole loop — decompose → fan out (parallel) → verify → synthesize — through Codex in one command, and prints a cited Markdown report.

~/.claude/skills/codex-research/research-run.sh \
  --out-dir <SCRATCH>/myresearch --max 5 --timeout 600 \
  "RESEARCH QUESTION"

• --max N caps both the number of sub-questions and parallel research jobs (default 5).
• --timeout S is per-codex-call (default 600).
• --depth quick|standard|deep — the depth knob. Sets Codex reasoning effort for every call: quick→low, standard→medium (default), deep→high. Deeper = more thorough and more cited, but slower. Verified live: --depth deep runs all calls at effort=high.
• --template default|brief|comparison — the report shape. Or pass a path to your own .md template. default = answer + per-topic findings + gaps; brief = bottom-line + key-findings bullets; comparison = TL;DR + at-a-glance table + per-option detail + recommendation. Verified live: --template comparison produced exactly that structure with no leftover placeholders.
• --no-verify skips the verification round; --verify-all verifies every finding (default: only non-high-confidence ones).
• Artifacts land in --out-dir: decompose.json, research/<slug>.json, verify/<slug>.json, synth-prompt.txt, and the final report.md. Each .json has a sibling .jsonl event log with the web searches Codex ran.

Verified live end-to-end in this container: a 3-sub-question run on "current stable versions + breaking changes of Node/Next/Prisma as of mid-2026" produced a fully cited report and even surfaced a real contradiction in Prisma's own docs about MongoDB support.

Scale via --max: 2–3 for a quick question, 6–8 + --verify-all for a thorough one.

---

Orchestration flow (what the Opus-high orchestrator does)

1. Scope. If the question is underspecified, ask 2–3 clarifiers first (same bar as /deep-research). Then write the question and success criteria down.

2. Decompose into 3–8 independent sub-questions. Independent = each can be researched without the answer to another.

3. Fan out. Spawn one Sonnet-low research subagent per sub-question, in a single message so they run in parallel. Each gets the driver command with a unique --out path. Agent-tool shape:

   Agent(
     subagent_type: "general-purpose",
     model: "sonnet", effort: "low",
     description: "codex research: <slug>",
     prompt: """
       Run ONE research task via Codex and return its result verbatim. Do not
       add your own knowledge. Run exactly:
   
       ~/.claude/skills/codex-research/codex-research.sh \
         --out <SCRATCH>/research/<slug>.json \
         --schema ~/.claude/skills/codex-research/findings.schema.json \
         --timeout 600 \
         "<SUB-QUESTION>. Use web search. Cite every claim with a source URL."
   
       Then print the contents of the --out file and the 'web searches' lines
       from the driver's stderr. If exit code != 0, report it and the stderr tail.
     """
   )
   

   Put all --out files under one research/ dir in the scratchpad so you can collect them.

4. Collect & verify (adversarial round). Read each --out JSON. For every finding that is not high confidence — and for any claim two agents disagree on — dispatch a Sonnet-low skeptic agent that runs codex-verify.sh:

   ~/.claude/skills/codex-research/codex-verify.sh \
     --out <SCRATCH>/verify/<slug>.json \
     --source "<the URL the finding cited>" --timeout 400 \
     "<the exact claim to check>"
   

   The skeptic is prompted to refute, not confirm, and returns {claim, verdict: confirmed|refuted|unclear, primary_source, note} (schema: verify.schema.json). Treat refuted/unclear findings as uncertain in the report. Distrust any claim whose sources are empty. Verified live: it confirmed a true claim (React 19 stable Dec 2024) and refuted a false one (correctly citing Next.js's Node 20.9 minimum, not 24).

5. Synthesize. Write the final report yourself (orchestrator): answer first, then sections per sub-question, every non-obvious claim carrying a source URL, and a "Gaps / low-confidence" section from the agents' gaps fields.

Scale the fan-out to the ask: a quick question → 2–3 agents, one verify pass. "Thorough" / "exhaustive" → more sub-questions, a dedicated verification round of skeptic agents, and a completeness check ("what sub-question did we not ask?").

---

Gotchas (each cost a real failed run here)

• --search is interactive-only. codex exec --search → error: unexpected argument '--search'. For exec, enable web search with -c tools.web_search=true. The driver already does this. Without it, Codex answers from stale training data.
• Model name is gpt-5.5 (per project convention). -m gpt-5.5 works.
• Pipe stdin to /dev/null. If stdin is a pipe/redirect, codex exec prints "Reading additional input from stdin..." and appends a spurious <stdin> block to your prompt. The driver runs codex with </dev/null.
• Sandbox = read-only. Research writes nothing to disk except the -o file (which is outside the sandbox). No need for workspace-write or --dangerously-bypass-*. Keep it read-only.
• Run outside a git repo. --skip-git-repo-check --ephemeral + a temp -C workdir so Codex doesn't try to attach to (or mutate) any repository. The driver makes its own mktemp -d.
• codex resets shell cwd on exit (prints "Shell cwd was reset to …"). Harmless — it's a message, not an error. Don't chain cd-dependent commands after it assuming cwd changed.
• Empty --out but exit 0 can happen if the model refuses/blank-answers; the driver flags this as a warning and returns non-zero. Re-dispatch with a rephrased prompt.

---

Troubleshooting

Symptom	Cause → Fix
error: unexpected argument '--search'	Using the interactive flag on exec. Use -c tools.web_search=true (driver does this).
Answer has no URLs / looks stale	Web search wasn't enabled, or the prompt didn't say "use web search". Check <out>.jsonl for web_search events; add "Use web search. Cite sources." to the prompt.
codex: command not found in a subagent	PATH lost the node/nvm bin. source your node version manager (e.g. ~/.nvm/nvm.sh) or use the absolute path from which codex.
Hangs near the timeout	Broad prompt → many searches. Narrow the sub-question or raise --timeout. Exit 124 = timed out; partial answer may still be in --out.
not logged in / 401 in <out>.jsonl.err	Codex auth lapsed. Ask the user: ! codex login.

---

Files

• codex-research.sh — the research engine (one Codex web-search task → cited file).
• codex-verify.sh — adversarial skeptic (refute one claim → verdict + primary source).
• research-run.sh — one-shot pipeline: decompose → fan out → verify → synthesize.
• findings.schema.json — structured-output schema for fan-out research results.
• verify.schema.json — schema for skeptic verdicts.
• decompose.schema.json — schema for the sub-question list.
• templates/{default,brief,comparison}.md — report shapes for --template.