codex-workflows

Claude Dynamic Workflows — on Codex

A Claude Code skill: type /codex-workflows <task> and a fleet of Codex (GPT) agents fans out across the work — Claude authors the workflow, runs it on your local codex app-server, and streams it back as a live execution map.

↑ a real run: diagnose a checkout latency regression — triage the signals in parallel, race three root-cause workers and cancel the losers, steer the winner on its warm thread, then gate the fix. This is the bundled demo; open it yourself in 10 seconds (below ↓).

You describe a task; Claude Code writes a dynamic-workflow script — agent() / parallel() / pipeline() / phase() / budget — and runs it across dozens of GPT-5 agents instead of Claude subagents. The runtime holds the loop, branching, and intermediate results, so your context only sees the final answer — and you watch it build as an interactive map. And unlike the native one-shot DSL, workers here can stay live — steer a worker on warm context, race several and cancel the losers, or let a controller adapt the plan as results land (Beyond one-shot ↓). It scales one level up, too: add --multi and Claude launches a whole fleet of concurrent workflows and supervises them itself — answering their gates, steering, killing dead ends, forking winners (walkthrough 8 ↓). Great for codebase audits, large migrations, cross-checked research, and idea generation.

This repo is two ways in:

1. The /codex-workflows skill — how you use it day to day, from the Claude Code TUI. Start here ↓
2. A standalone runner + viewer — the same engine without Claude Code (a CLI, near the end).

Unofficial / community project. Not affiliated with OpenAI or Anthropic. "Codex" and "Claude" are trademarks of their respective owners.

---

See it now (no Codex required)

Want a look at a finished run before installing anything? The viewer is offline and self-contained, and the flagship demo is bundled:

git clone https://github.com/scasella/claude-dynamic-workflows-codex
cd claude-dynamic-workflows-codex
node runner/bin/view-run.js examples/incident-demo --open

That opens the map above — a fictional checkout-latency incident: a parallel triage, a race of three sessionful root-cause workers (the winner is steered for a confirming second turn; the two losers are cancelled, marked ⊘), and a lone fix gate. Click any node for its full result; click the n+1 worker to see its per-turn timeline; F frames the graph, drag to pan, scroll to zoom.

Map — the run as a DAG. Workers carry a ⟳ N badge and a turn-chip strip.	Worker timeline. Click a worker → every turn on its one warm thread.
Cockpit. A live run paused at a human() gate — answer it right in the page.	Light theme. Toggle Dark/Light top-right; there's a dense Tree layout too (below).

The first thing you'll notice is what's not in the old one-shot model: long-lived workers (⟳ 2 turns), a race that cancelled its losers, and — live — an answer card the run is waiting on. The rest of this guide is how to drive all of that from Claude Code.

---

Install

As a Claude Code plugin (recommended — updates with every push):

/plugin marketplace add scasella/claude-dynamic-workflows-codex
/plugin install codex-workflows@codex-workflows

Or as a classic skills-dir clone:

git clone https://github.com/scasella/claude-dynamic-workflows-codex ~/.claude/skills/codex-workflows

(Developing from a clone elsewhere? npm run sync-skill pushes the skill surface — SKILL.md, references/, examples/, runner/ — to ~/.claude/skills/codex-workflows in one command.)

Prerequisites

• Node ≥ 18 (zero npm dependencies to install)
• The codex CLI on your PATH, logged in: codex login

Either way the skill is now available in Claude Code as /codex-workflows. Verify Codex is reachable any time with:

npx github:scasella/claude-dynamic-workflows-codex doctor   # → state: ready

(The same npx entrypoint exposes the whole CLI surface without installing anything: run, fleet status|answer, view, map, summarize.)

---

Using it in Claude Code

The skill is manual-invoke only — Claude never auto-triggers it. You type /codex-workflows and describe the task in one or two rough sentences — there's no need to pre-engineer a prompt; the skill compiles your rough intent into the right workflow itself:

/codex-workflows  Audit every route under src/ for missing auth checks

Behind that one line, Claude:

1. Preflights Codex — confirms the app-server is reachable and notes the latest frontier model.
2. Compiles your rough intent into a concrete harness — picks the scale, archetype, and pattern, builds a task contract, and states its assumptions (no external "metaprompt" needed).
3. Authors a workflow script into your project (./<name>.workflow.js) — so you can read it, tweak it, and rerun it.
4. Runs it on Codex, pinning every agent to the latest frontier model (gpt-5.6-sol today) and scaling thinking effort to the harness — a small run goes flat --effort medium, while a bigger one uses --auto-effort so a lone judge/synthesize gate gets the policy's extra-high tier (xhigh) and wide fan-outs floor at high.
5. Surfaces the outcome right in the conversation — a summary, the script path, and the run's execution map rendered inline as text:

╭─ ◆ market-news ──────────────────────────────────────────────────────────────╮
│ ✓✓✓✓✓✓  6/6 done · 2 phases · 701k tok · 20m27s · gpt-5.5                    │
╰──────────────────────────────────────────────────────────────────────────────╯
  │
  ▼ ① Gather ───────────────────────────────────  5 agents · 622k tok · 17m38s
      AGENT      MODEL    EFFORT  TOKENS    WALL
  ├─✓ indices    gpt-5.5  high       52k   1m26s
  │   S&P 500 rose 0.4% to a record 6,012; Nasdaq +0.6% and Dow +0.3% close.
  ├─✓ movers     gpt-5.5  high      140k   5m16s
  │   Nvidia gained ~3% on AI demand; a major retailer slid 8% on guidance.
  ╰─✓ catalysts  gpt-5.5  high      128k   3m27s
      Several megacap earnings beat after the bell; Fed stayed data-dependent.
  ┄ barrier · Gather → Synthesize ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
  ▼ ② Synthesize ──────────────────────────────────  1 agent · 79k tok · 2m49s
  ╰─✓ brief      gpt-5.5  xhigh      79k   2m49s
      Fed, jobs and AI earnings kept stocks near records into June 3.
  │
  ▼
╭─ ✦ result ───────────────────────────────────────────────────────────────────╮
│ Fed, jobs and AI earnings kept stocks near records into the June 3 close.    │
╰──────────────────────────────────────────────────────────────────────────────╯

The captured output above is preserved from a GPT-5.5 run. The current GPT-5.6 Codex series is Sol (flagship), Terra (balanced), and Luna (efficient). This skill deliberately does not route stages across those tiers: --frontier dynamically detects the current flagship and pins the whole run to that one model.

Steering your run — just ask

You don't manage flags; you describe what you want and Claude wires it up. Common asks:

You want to…	Say something like…	What Claude does
Watch it build live	"…and let me watch it" · "open the live GUI"	opens a browser viewer (--gui) and/or a new-terminal ASCII map (--tui) that update in place as agents run
See the size/cost first	"plan it first — how many agents, roughly how much?"	a no-token dry run (--plan) that counts agents per phase and estimates a budget
Cap the spend	"keep it under ~5M tokens"	a hard --budget ceiling — tripping it isn't fatal, it prints a one-line --resume to continue
Keep it read-only (safety)	"read-only — don't let agents write files"	runs every agent with --sandbox read-only — a safety choice (agents read but never write); good for audits, research, exploration. Not a way to spend less.
Let it edit files	"let it apply the migration"	--sandbox workspace-write (the default) so agents can write
Resume after a stop	"resume that run"	replays already-finished agents from the journal free, runs only the rest; sessionful workers re-attach to their persisted threads warm
Be asked before risky steps	"check with me before applying anything"	authors a human() gate — the live viewer shows an answer card (choices + free text) right in the run page; the run waits there, fleet warm, and falls back to a safe default on timeout
Pick a specific pattern	"do a loop-until-dry bug hunt" · "fresh-context review with independent reviewers"	authors that exact pattern (see the pattern library)
Run a supervised fleet	"--multi" · "throw a few different harnesses at this at once"	launches 2–4 concurrent variant workflows in the background and supervises them itself — polls fleet status, answers their gates, steers, kills dead ends, forks winners, then synthesizes across runs (see walkthrough 8)

One thing you don't tune: it's always one frontier model for every agent — no model-mixing. Thinking effort scales to the harness instead (a quick 2–5-agent run goes flat --effort medium; bigger runs use --auto-effort, so lone judge/synthesis gates think hardest). To spend less, lower the budget, drop the effort, narrow the fan-out, and --plan first to size it — never a smaller model. (Read-only is a safety choice — what agents may touch — not a cost lever.)

Example invocations