Codex workflow

Codex Workflow

Deterministic multi-agent orchestration in Codex - the analog of Claude Code's Workflow tool. Pick the right level for the job.

Three levels (cheapest first)

Need	Use	Determinism
Ad-hoc "spawn one agent per X, summarize" in a chat	native NL spawn	low (model decides)
Fixed fan-out over a worklist (one worker per row, schema'd)	spawn_agents_on_csv	medium
Collision-free parallel implementation	worktree + codex exec &	high (isolated)
Scripted multi-step pipeline with structured output you parse	run_workflow (the orchestrator MCP)	high

Reach for run_workflow when you'd otherwise hand-wire codex exec calls; reach for the native paths for quick in-session work.

run_workflow - the orchestrator

Installed as the codex-workflow MCP extension (vd mcp install codex-workflow). Call the run_workflow tool with a spec:

{
  "steps": [
    { "id": "scan",   "prompt": "List changed files vs main.", "output_schema": {"type":"object","properties":{"files":{"type":"array"}}} },
    { "id": "review", "prompt": "Review {file} for bugs.", "agent": "code-reviewer", "parallel_group": "g1" }
  ]
}

• v1 shape: sequential steps + one parallel_group + per-step output_schema. NOT loops/conditionals (those are a later iteration - script them outside, or use multiple run_workflow calls).
• agent (optional) names a ~/.codex/agents/*.toml role; its developer_instructions are injected as a prompt override (see #26363 below).
• Concurrency is capped by [agents].max_threads (config).
• Returns one structured result per step: {id, status, output}.

Native fallbacks (no orchestrator needed)

If run_workflow (or any code-mode wrapper) fails with a missing codex-code-mode-host, the machine has the standalone codex cask without ChatGPT.app - the shared plugin runtime's file-access host ships only inside /Applications/ChatGPT.app. Don't retry the wrapper; disable the broken feature with codex -c features.code_mode=false, or drop to raw codex exec -s read-only -C <dir> (prompt via stdin, -o for output) or the fallbacks below.

spawn_agents_on_csv - deterministic batch

One worker per CSV row; each calls report_agent_job_result exactly once. Params: csv_path, instruction (with {column} placeholders), id_column, output_schema, output_csv_path, max_concurrency. Best for "review/audit/transform one file|package|service per row." See references/native-orchestration.md.

worktree + codex exec & - collision-free parallel writes

Pairs with vd:worktree. One worktree + background codex exec per task; wait. Each agent writes in isolation, no merge collisions mid-flight.

Natural-language spawn

"Spawn one agent per review point, wait for all, summarize each." Codex orchestrates spawn/route/wait/close. Lowest ceremony, lowest determinism - keep fan-out at 3–5 (token cost is linear; human review is the real ceiling).

Patterns (translated from Claude's Workflow)

• Loop-until-dry: repeat a finder step until K rounds return nothing new (script with repeated run_workflow calls).
• Adversarial N-vote verify: a parallel_group of N skeptics per finding; keep if majority confirm.
• Multi-modal sweep: parallel steps each searching a different way, blind to each other.
• Pipeline: chain run_workflow calls, feeding step outputs forward.

Caveat - regression #26363 (while open)

Since Codex v0.137.0, custom ~/.codex/agents/*.toml are not selectable at in-session spawn (generic fallback). run_workflow works around it by injecting the named agent's developer_instructions as a prompt override. For raw NL spawns, do the same by hand: paste the role's instructions into the spawn prompt. Drop this workaround when OpenAI restores agent_type selection.

Install & enable

The run_workflow tool ships as the codex-workflow vd extension (Python/uv MCP server). Prereqs: uv + codex login (model work runs through your Codex login - no extra API key).

cd ~/vd-cli && go build -o ~/.local/bin/vd ./cmd/vd   # if vd lacks `mcp` (prefix env -u GOROOT if GOROOT is mise-pinned)
vd mcp install codex-workflow              # Codex (~/.codex/config.toml) + Claude (project ./.mcp.json)
vd mcp install codex-workflow --scope user # …or Claude global (~/.claude.json)
vd mcp list && vd mcp doctor               # verify
# then RESTART Codex / Claude Code to load the server

Scope only changes the Claude target (project → ./.mcp.json, user → ~/.claude.json); Codex always uses its global config.toml.

Integration

• Composes: vd:worktree (parallel writes), the ~/.codex/agents/*.toml roles.
• Install/manage: vd mcp install|list|enable|disable|doctor codex-workflow.