codex-workflow

Codex-in-Workflow (Pattern A)

Authoring custom Workflows with the Workflow tool (agent(), pipeline(), parallel(), phase(), schemas, loop-until-dry, etc.) is assumed knowledge. This skill is the know-how for mixing Codex headless into one so that the orchestration stays Claude's but selected nodes run on a different model family.

Mental model

A Workflow's agent() normally spawns a Claude subagent. Pattern A keeps every orchestration primitive exactly as-is and only changes who does the work at chosen nodes: a "codex node" is a normal agent() whose subagent does nothing but shell out to codex exec and relay its output back.

Workflow (Claude JS orchestration)
 ├─ find / generate ............... Claude agent()  ← Claude is broad, fast, cache-warm
 └─ verify / judge / 2nd-opinion .. codex node      ← GPT, independent failure modes

The value is diversity, not replacement. Two model families disagree in different places, so a Codex verifier catches Claude's correlated false positives (and vice versa) in a way that N more Claude verifiers cannot. The single highest-ROI use is adversarial verification: Claude finds, Codex tries to refute.

Prerequisites — preflight before trusting any codex node

This skill assumes the Codex CLI is installed and authenticated in the environment running the Workflow. Do NOT assume a specific version or default model — confirm them, because they change between installs. Run the preflight (CLI present, auth live, structured-output path works) from references/codex-headless.md once before relying on any node; if it errors on auth, the user must codex login (interactive) — that cannot be done headlessly.

Step 0 — should this task even use Codex?

Don't bolt Codex on for its own sake; each node costs a separate Codex/OpenAI run plus a Claude wrapper turn. Route a node to Codex only when a second, independent model materially de-risks the result:

• Yes: verifying findings/claims, judging candidates, an independent attempt in a diverse panel, sanity-checking a risky Claude conclusion.
• No / don't blend when:
  • it's bulk throughput work (Claude subagents are cheaper, faster, cache-warm);
  • it's a correlated check — Codex would only re-derive from the same evidence Claude already used, with no independent angle (an echo, not a second opinion);
  • it's a blind check — the node can't give Codex what it needs to verify independently (no files/tools in read-only, and the evidence isn't inline);
  • there's no verifiable/judgeable artifact (pure open-ended ideation) — diversity adds noise, not signal.