Port Claude Code Workflows to Codex

Key Takeaways

• gpt-workflow brings Claude Code-style deterministic workflows to Codex CLI with resumable journals and JSON schema validation.
• Install via Codex plugin and store workflows under .codex/workflows/.

What Changed

A new open-source project, gpt-workflow, brings deterministic multi-agent workflows to Codex CLI. Think of it as Claude Code's workflow system, but for OpenAI's Codex App Server.

Instead of driving Codex with ad-hoc prompts, you write workflows as plain JavaScript files. Control flow—loops, branches, retries—is just JavaScript. The agent() function delegates bounded judgment to Codex threads, and parallel(), pipeline(), and child workflow() calls fan that work out.

What It Means For You

If you use both Claude Code and Codex CLI, this bridges a gap. Claude Code has hooks, MCP, and CLAUDE.md for structured workflows. Codex CLI now gets three capabilities that were previously missing:

1. Resumability. Long or token-expensive runs replay completed calls from a durable journal. You don't pay tokens again for work already done. If a run crashes at step 47, resume from step 42—not step 1.

2. Validated structured output. Pass a JSON schema to agent() and the runtime validates the reply and retries invalid ones. No more policing format in prompt text.

3. Multi-agent verification. Independent critics and judge panels, where a failed call resolves to null instead of aborting the fan-out. You can run 10 agents in parallel, filter out failures, and continue.

Try It Now

Installation (preferred: Codex plugin)

codex plugin marketplace add CyrusNuevoDia/gpt-workflow
codex plugin add gpt-workflow@gpt-workflow

Restart the ChatGPT desktop app after installing and start a new task so the bundled skill loads.

Or install globally

bun add --global gpt-workflow

Requirements: Bun 1.3 or newer. Node.js is not supported.

Your first workflow

Store project workflows under .codex/workflows/. Here's summarize-files.js:

export const meta = {
  name: "summarize-files",
  description: "Summarize files concurrently and merge the findings"
}

const files = args.files

const summaries = await parallel(
  files.map((file) => () =>
    agent(`Read ${file} and return three factual bullets.`, {
      label: `summarize:${file}`
    })
  )
)

return { summaries: summaries.filter(Boolean) }

args is the run's input. If an agent's thread errors, times out, returns no final message, or exhausts structured-output retries, that call resolves to null. The filter(Boolean) drops those slots cleanly.

Run it

gpt-workflow run --default-model gpt-5.6-luna \
  --args '{"files":["src/cli.ts","src/runtime.ts"]}' \
  .codex/workflows/summarize-files.js

Resume a failed run

gpt-workflow run --default-model gpt-5.6-luna --resume workflow-123 \
  --args '{"files":["src/cli.ts","src/runtime.ts"]}' \
  .codex/workflows/summarize-files.js

Resume replays completed calls from the journal—their tokens are not spent again—then runs the rest live.

Structured output with validation

const result = await agent("Extract the function signatures", {
  schema: {
    type: "object",
    properties: {
      functions: {
        type: "array",
        items: {
          type: "object",
          properties: {
            name: { type: "string" },
            params: { type: "array", items: { type: "string" } },
            returnType: { type: "string" }
          },
          required: ["name", "params", "returnType"]
        }
      }
    },
    required: ["functions"]
  }
})

The runtime validates the reply against the schema and retries invalid ones automatically.

Why This Matters for Claude Code Users

If you're invested in Claude Code workflows, this project shows the pattern is spreading. The same deterministic, resumable, multi-agent architecture that makes Claude Code powerful for production is now available on Codex CLI. The knowledge transfers: CLAUDE.md patterns, hook-based verification, and structured output schemas all map to this paradigm.

For teams that need to run across both platforms, gpt-workflow provides a unified mental model. Write workflows once, run on either Claude Code or Codex CLI with minimal adaptation.

Caveats

• Workflow source runs inside node:vm as a semantic boundary, not a security sandbox for hostile JavaScript. Don't run untrusted workflows.
• Live runs spend model tokens. Resume is the cost-saver.
• Bun 1.3+ only. No Node.js support.

Source: github.com