Skip to content
Skills Library
AI & agents · Automation

codex-workflow

/codex-workflow

Run deterministic multi-step agent workflows in Codex - fan-out, parallel, schema-validated structured output - via the codex-workflow MCP orchestrator (run_workflow), with native in-chat fallbacks. Use when you want Claude-Code-Workflow-style orchestration in Codex: 'run a workflow', 'fan out subagents', 'review each file in parallel', 'orchestrate these steps'. Triggers: 'codex-workflow', 'run_workflow', 'orchestrate in codex'.

Repository
skills ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Run deterministic multi-step agent workflows in Codex - fan-out, parallel, schema-validated structured output - via the codex-workflow MCP orchestrator (run_workflow), with native in-chat fallbacks. Use when you want Claude-Code-Workflow-style orchestration in Codex: 'run a workflow', 'fan out subagents', 'review each file in parallel', 'orchestrate these steps'. Triggers: 'codex-workflow', 'run_workflow', 'orchestrate in codex'.

Triggers from the description

run a workflowfan out subagentsreview each file in parallelorchestrate these stepscodex-workflowrun_workfloworchestrate in codex
Original author description

Run deterministic multi-step agent workflows in Codex - fan-out, parallel, schema-validated structured output - via the codex-workflow MCP orchestrator (run_workflow), with native in-chat fallbacks. Use when you want Claude-Code-Workflow-style orchestration in Codex: 'run a workflow', 'fan out subagents', 'review each file in parallel', 'orchestrate these steps'. Triggers: 'codex-workflow', 'run_workflow', 'orchestrate in codex'.

How it works

  1. Three levels (cheapest first)
  2. runworkflow - the orchestrator
  3. Native fallbacks (no orchestrator needed)
  4. Patterns (translated from Claude's Workflow)
  5. Install & enable
  6. Integration
Original SKILL.md headings · 74 lines, 613 words
SKILL.md preview
---
name: codex-workflow
description: "Run deterministic multi-step agent workflows in Codex - fan-out, parallel, schema-validated structured output - via the codex-workflow MCP orchestrator (run_workflow), with native in-chat fallbacks. Use when you want Claude-Code-Workflow-style orchestration in Codex: 'run a workflow', 'fan out subagents', 'review each file in parallel', 'orchestrate these steps'. Triggers: 'codex-workflow', 'run_workflow', 'orchestrate in codex'."
license: MIT
metadata:
  author: vanducng
  version: "1.0.0"
---

# 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:

```jsonc
{
  "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 into that step's prompt.
- 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](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.

## 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).

Every `vd mcp` subcommand needs `VD_EXTENSIONS_DIR` pointing at a vd-cli checkout:

```bash
export VD_EXTENSIONS_DIR=<vd-cli-checkout>/extensions
cd <vd-cli-checkout> && 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 (same VD_EXTENSIONS_DIR)
# 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`.
Files in this package (2)
  • SKILL.md 5 KB
  • references/native-orchestration.md 3 KB

Versions

The database has no other skills named codex-workflow.

Database snapshot: 13.11.2026 · package version 6a519669489d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90workflow
    Create, run, monitor, cancel, or resume deterministic JavaScript workflows that orchestrate multiple Codex, Claude, Cursor, or Kimi agents. Use for parallel investigation or review, staged agent pipelines, resumable long-running work, or when the user explicitly asks for a…
  • 100workflow-builder
    Design and write deterministic multi-agent workflow scripts (.js files in .claude/workflows/) for Claude Code's Workflow tool. Use when a user wants to build, create, author, scaffold, or run a custom Claude Code workflow, orchestrate sub-agents (fan-out, pipeline, loop,…
  • 100dynamic-workflow
    Design and orchestrate Claude Code dynamic workflows — the new multi-agent system that fans out 10-100 subagents in parallel with verification. Teaches when to use workflows vs single-agent, how to structure fan-out/fan-in patterns, and how to build verification gates. Use when…
  • 98workflow
    Deterministic multi-agent orchestration powered by the GitHub Copilot CLI. Use when asked to "run a workflow", "orchestrate", "fan out agents", "run agents in parallel", "spawn subagents", or to decompose a job across many independent agents — audits, code review, sweeps,…
  • 100codex-orchestrate
    Claude Code only. Use when the user explicitly invokes /agents-bridge:codex-orchestrate (or /codex-orchestrate) in Claude Code or asks Claude to orchestrate a large multi-slice plan by delegating implementation to the Codex CLI through agents-bridge. In native Codex, use $slice-runner instead.
  • 98dynamic-workflow
    Create, review, run, inspect, pause, resume, and cancel durable JavaScript workflows that coordinate multiple headless Codex agents. Use for dynamic fan-out and fan-in, per-item analysis, multi-stage agent pipelines, loops or branches driven by worker results, long background…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.