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

# Audit — scan in parallel, then a skeptic confirms each finding
/codex-workflows  Audit every route under src/ for missing authorization, read-only

# Research — fan out across the web, cross-check every claim, cite the survivors
/codex-workflows  Research the current state of on-device LLM inference and verify each claim, then watch it live

# Brainstorm — generate, dedup, judge, recommend (plan it first to see the cost)
/codex-workflows  Brainstorm 10 product ideas from this repo, score them with 3 judges, recommend the top 3 — plan it first

# Review — producer drafts, independent reviewers sign off (no agent reviews its own work)
/codex-workflows  Review the files I changed for bugs with a fresh-context review gate

# Triage — classify a batch in parallel, dedupe, route (untrusted text stays read-only)
/codex-workflows  Triage these 40 issues and route each to a team

# Migrate — find every call site and rewrite it (needs write access)
/codex-workflows  Find every call of legacyFetch() and migrate it to the new client, then apply the edits

# Harden a goal — lint a vague /goal into a precise, testable one before you spend a fleet (goal_lint)
/codex-workflows  Harden this Codex goal before I run it

# Claim-check — verify a draft's claims against the actual repo, refute the unsupported ones (claim_check)
/codex-workflows  Verify this blog draft against the repo

# Invent — net-new-to-industry product ideas, not thin wrappers; judged and recombined (industry_invention_studio)
/codex-workflows  Generate practically useful, net-new product ideas from this repo

# Triage a result — decide real / overfit / continue, then write the next experiment's /goal (research_result_triage)
/codex-workflows  Triage the latest research result and write the next /goal

# Fleet — several concurrent workflows, supervised by Claude (answers gates, steers, kills, forks)
/codex-workflows --multi  Find the cause of the checkout p99 regression — attack it from a few different angles at once

Rough intent is the default — a sentence or two is enough, and the skill compiles the rest (scale, archetype, pattern, task contract, safe run settings). Add prompt-only if you just want the generated invocation without running it.

Following a run

• Claude renders the execution map inline as the run progresses and again when it lands — so you can follow it without leaving the conversation.
• For the full browser GUI at any time, just ask Claude to open the viewer (it runs view-run on the run's journal).
• For a cost & reliability recap — tokens by phase, the costliest/slowest agents, and any red flags — ask Claude to summarize the run (it runs summarize-run on the journal); a short version also prints automatically when a run finishes.
• To see across runs — what each run cost, completion rates, and how the same workflow trends run-over-run — ask Claude to compare the runs (it runs compare-runs over the journals; one line per run plus per-workflow rollups like "avg 1.2M tok/run · latest vs prev: −20%").
• Every run is journaled to <project>/.workflow-journal/<name>.jsonl; ask Claude to open the last run in the viewer to revisit a past run.
• The script Claude wrote stays in your project — rerun or edit it directly, or ask Claude to adjust it.

Not what you wanted? If you actually want Claude subagents (not Codex), use Claude Code's native Workflow tool instead — this skill deliberately routes the work to Codex/GPT.

---

Real-world walkthroughs

Each of these is one rough sentence to /codex-workflows. Claude compiles it into the harness described, runs it on Codex, and hands you the artifact — you watch it build the whole time. These are the shapes people actually reach for.

1 · Diagnose a production incident (the bundled demo)

/codex-workflows Checkout p99 just spiked 12×. Triage the signals, race a few root-cause theories, confirm the leading one, and propose a fix — read-only, and ask me before you suggest shipping anything.

Claude authors a root-cause lab: a parallel Triage (metrics · logs · recent deploys), then a Hunt that races three live workers — one per hypothesis (N+1 query, pool exhaustion, cache stampede). The first to land wins; the runtime cancels the other two (you don't pay for the slowest). The winning worker is then steered on its warm thread — "confirm on the held repro" — a cheap second turn that doesn't re-read anything (141k tokens for the hunt → 47k for the confirmation). It pauses at a human() gate for the ship decision, then a lone xhigh synthesizer writes the patch + a regression test. The whole run is the hero image above; click the n+1 worker for the per-turn timeline, and the live run shows the answer card (the cockpit screenshot). Bundled — open it with node runner/bin/view-run.js examples/incident-demo --open.

2 · Audit a codebase for a class of bug — and trust the result

/codex-workflows Audit every route under src/ for missing authorization, read-only. Have an independent skeptic try to refute each finding before you report it.

The classic find → adversarially-verify shape, and the reason to use a fleet instead of one agent: one pass finds candidates in parallel (one agent per area), then a second, independent agent tries to refute each — defaulting to "not a real finding" unless it can prove exploitability with a file:line. Plausible-but-wrong findings die in verification instead of in your inbox. You get a deduped table of confirmed issues with evidence, and (because it's --sandbox read-only) nothing was ever written. Swap "authorization" for "missing input validation", "unhandled promise rejections", "N+1 queries", "PII in logs" — same harness.

3 · Load a big thing once, then interrogate it cheaply

/codex-workflows Read everything under packages/core into one worker, then I'm going to ask it a stream of questions — keep it warm.

This is the sessionful superpower the native one-shot DSL can't do. One worker ingests the corpus once (agent.start); every follow-up is a session.steer on the same warm thread — it answers from context instead of re-reading. Measured on this repo's own source: after the one-time load, follow-ups cost ~69k tokens in ~6s each versus ~219k and ~97s for a cold agent re-reading every time — ~3× cheaper, ~16× faster per question (benchmark). Works for a data room, a contract set, a spec bundle, a log archive — anything you'll question more than twice.

4 · Throw several strategies at one stubborn bug

/codex-workflows This flaky test fails ~1 in 20. Try three theories at once — a recent regression, a timing/ordering race, and a shared-state leak — and tell me whichever one cracks it first.

A hedged race: three workers attack the same problem from different angles in parallel; agent.waitAny wakes you on the first to reach a conclusion, and the losers are cancelled on the spot. You stop paying for the two dead ends the moment the live one pays off — the opposite of a parallel() barrier that waits for (and bills) the slowest. Reach for it whenever the cheapest path to an answer is unknown and trying several beats committing to one.

5 · Let it do the work — but stop at the decisions only you should make

/codex-workflows Migrate every call of legacyFetch() to the new client and apply the edits — but show me the plan and check with me before you touch anything in payments/.

The cockpit. Claude authors a migration that discovers every call site, drafts the rewrites, and at the risky fork calls human("apply to payments/ now, or open a PR?", {choices}). With --gui, the run pauses and an answer card appears right in the live viewer (the cockpit screenshot) — the whole fleet stays warm while it waits for your click. Unattended (CI, overnight) it falls back to the safe default after a timeout instead of hanging, and your answer is journaled so a --resume never re-asks. Supervised autonomy: the agents do the labor, you keep the judgment calls.

6 · The trust loop — harden the instruction before, verify the claims after

Before: /codex-workflows quick Harden this Codex /goal before I run it: [paste] · After: /codex-workflows Verify this PR description's claims against the actual diff and repo.

Two shipped harness-zoo templates that bracket any expensive run. GoalLint turns a vague, risky /goal into a precise, falsifiable, artifact-producing one — so you stop getting runs that end in "looks good" with no controls and no stopping criteria. ClaimCheck extracts every factual claim in a doc (README, PR, report, agent output), verifies each against repo artifacts, marks them supported / unsupported / contradicted / plausible-unverified, and emits a proof ledger with safer rewrites for the ones that don't hold. Harden before agents run; verify the claims after they write.

7 · Cross-checked research with source discipline

/codex-workflows Research the current state of on-device LLM inference, verify every claim against a source, and cite the survivors — watch it live.

A research fan-out that's honest about what it knows: parallel searches gather candidate claims, an independent pass verifies each against a real source (and reports gaps rather than fabricating when the evidence isn't there), and a synthesizer writes the cited brief. Confirmed evidence, inference, and uncertainty stay separated — missing evidence is treated as uncertainty, not success.

8 · Run a whole fleet — and let Claude supervise it

/codex-workflows --multi Find the cause of the checkout p99 regression — attack it from a few different angles at once, and keep the total under 5M tokens.

With --multi, Claude stops being a launcher and becomes the operator. It compiles a fleet plan — say, a sessionful deep-dive on the ORM theory, a loop-until-dry sweep of recent diffs, and a log-forensics fan-out — and launches each as its own background run in one shared directory, budget split across them. Then it runs the supervision loop the runner was built for: fleet status rolls every run into one digest (who's running, who's stalled, who's waiting on an answer, who finished and what they returned), gates push instead of waiting to be polled (--notify-cmd fires a shell hook the moment a question goes pending or a run ends), and the workflows are authored with supervisor checkpoints — human() gates whose answers Claude itself supplies via fleet answer, with free text acting as a steer ("drop the cache theory, go deep on the ORM layer"). A run chasing a dead end gets killed and its tokens stop; a run onto something big gets forked — copy the journal, extend the variant, --resume replays everything already done at 0 tokens and sessionful workers re-attach to their threads warm. At the end Claude reconciles the variants' results — including what the killed runs ruled out — into one answer with per-variant costs.

_{↑ the live fleet dashboard mid-supervision: the deep investigator is waiting on a steer (free text = a directive, with the paste-ready answer command right under it), the diff sweep is mid-verify, and log-forensics has already returned its verdict.}

You're never locked out of the loop: the same checkpoints stay human-answerable in the --gui cockpit, and fleet status --watch --html fleet.html --open gives you a live fleet dashboard (above) — one card per run, auto-refreshing, with paste-ready answer commands under every pending gate. The difference is you no longer have to be there. (examples/fleet is the runnable two-variant version with the full transcript.)

And the supervision layer isn't limited to workflows — it's a documented file contract (fleet-protocol.md), and the bundled supervise shim wraps any long-running command in it:

npx github:scasella/claude-dynamic-workflows-codex supervise --name nightly -- python run_evals.py

The job appears in fleet status and the dashboard like any run, its output streams as live progress, and a one-line @@ASK {"question":"Promote?","choices":["yes","no"],"default":"no"} printed by the job becomes a real supervisor gate — the answer lands on the job's stdin (read answer in bash), with the safe default on timeout. Your deploy script, eval run, or data job gets the same supervised-autonomy treatment as a workflow fleet.

This isn't hypothetical — this repo dogfoods it. A --multi fleet was pointed at its own docs before this README shipped: two variants checked 90 documentation claims and walked the fresh-user install story, adversarially verified their own findings (8 flagged → 6 survived the refuters), and every confirmed issue was fixed — including one of them becoming a permanent CI suite.

Sizing & cost. Unsure how big a run will be? Add "plan it first" — a no-token dry run prints the agent count per phase and a budget estimate before you spend anything. Add "keep it under ~5M tokens" for a hard ceiling (tripping it is recoverable — it prints a free `-