codex-workflow

Files (2)

• SKILL.md
• native-orchestration.md · references/

SKILL.md (first lines)

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

From vanducng/skills, MIT.

More from vanducng/skills