Codex Workflows

Codex Workflows

Run a Claude Code dynamic-workflow script against a local Codex App Server. The authoring surface is identical to native dynamic workflows — export const meta plus a body using agent(), parallel(), pipeline(), phase(), log(), args, budget, workflow() — but every agent() call runs as one Codex (GPT) thread+turn instead of a Claude subagent.

Manual-invoke only. Claude does not auto-trigger this skill (disable-model-invocation: true); it runs only when the user types /codex-workflows or explicitly asks for a Codex workflow. Once invoked, follow the loop below — the work runs on Codex/GPT agents. If the user actually wanted Claude subagents, say so and point them at the native Workflow tool.

RUNNER below means the bundled runner directory: runner/ relative to this skill's base directory (shown when the skill loads). For a classic skills-dir install that is ~/.claude/skills/codex-workflows/runner — the literal paths in the examples below assume it; substitute your base directory if this skill is installed as a plugin. It is dependency-free Node ≥ 18.

Default rough-intent mode

One or two rough sentences is enough. You do not need to hand this skill a fully-engineered spec — describe what you want (e.g. /codex-workflows Harden this goal before I run it) and the skill compiles it into an operational harness itself: it classifies the job, picks the smallest workable scale, an archetype, and a harness pattern, builds a task contract, composes phases, casts personas, applies the quality/epistemic standards, authors the script, picks safe run settings, and runs it — stating its assumptions as it goes.

Operating rules in this mode:

• The rough intent is the contract. Make reasonable assumptions for anything left

unspecified and state them; do not interrogate the user with follow-ups.

• Choose the smallest useful harness, not the largest possible one (see the

Anti-overbuild rule).

• Do not emit a giant prompt for the user to paste back. Compile and proceed to

authoring/running. (The one exception is prompt-only mode — see Mode detection.)

• This replaces any external "metaprompt": the expansion now happens inside the

skill. The whole Compiling rough intent into a workflow section below is that compiler.

Default execution checklist

Every run, in order (the sections below expand each step):

1. Preflight Codex once (handshake.js); note the latest frontier model.
2. Compile the rough intent: classify the job → scale → archetype → pattern

(name the failure mode it prevents) → task contract. State your assumptions.

1. Author the script into the repo (./.workflow.js).
2. Settings: --frontier · effort by scale (--effort medium for a

quick_harness, --auto-effort for standard/deep) · --sandbox read-only unless it must write · a bounded --budget · strict schemas (additionalProperties:false).

1. Size it — run --plan first for any expensive or complex workflow.
2. Run on the Codex runner (never the native Workflow tool).
3. Surface — inline ASCII map + summarize-run highlights; cite the script,

journal, viewer, report, and run-summary paths (see Output behavior).

Mode detection

Read the mode from the user's phrasing, then behave accordingly:

| Mode | Trigger | Behavior | |------|---------|----------| | default (rough-intent) | 1–2 rough sentences | Compile internally → author → run. State assumptions. | | --multi (fleet) | the --multi flag, or "fleet" / "several workflows at once" | Compile a fleet plan (2–4 concurrent variant workflows, similar and/or diverse), launch them in the background, and supervise: poll fleet status, answer gates, steer, kill, fork, then synthesize. See Fleet mode. | | prompt-only | "prompt-only", "just the invocation", "don't run it" | Emit a complete /codex-workflows invocation/spec (the A–L structure below) and STOP — do not author or run. | | write-only | "write it but don't run", "author only" | Author the workflow script, print its path, stop before running. | | run-existing | a script path or saved-workflow name is given | Skip compilation; run that script/name through the runner. | | quick | "quick", "small", "cheap" | Bias to a quick_harness (2–5 agents). | | deep | "deep", "thorough", "exhaustive" | Allow a larger / deep_harness; justify the size. | | no-write | "don't write files", "just tell me" | Return final JSON/Markdown only; no report/source files; --sandbox read-only. |

Two precedence rules: if the user gives a script path or saved name, run it (don't recompile). If the user gives a detailed spec, honor it as written but still apply the safety + run defaults below. Otherwise it's rough intent → compile.

In prompt-only, the invocation you emit follows the same A–L structure the skill builds internally: A name · B purpose · C task contract · D inputs / context reconstruction · E phases · F personas · G anti-wrapper standards · H outputs · I run settings · J safety / epistemics · K final-response format · L productization. Then stop — do not run.

The loop

In default rough-intent mode, do steps 1–2 silently and state your assumptions before authoring. The mechanics below — handshake, the run command, the inline map — are unchanged; steps 2 and 4 are where rough intent gets compiled.

1. Preflight — once per session, or whenever a run fails to connect, confirm

Codex is reachable and authed: ``bash node ~/.claude/skills/codex-workflows/runner/test/handshake.js ` It prints state: ready and the available models. If it fails, tell the user to run codex login (the runner needs a logged-in codex CLI on PATH). From that list, note the **latest frontier model** — the newest flagship general model (not a -mini/-spark variant; model/list flags it isDefault and its description calls it the strongest). The GPT-5.6 Codex series is Sol (flagship), Terra (balanced), and Luna (efficient); today the frontier is gpt-5.6-sol`. Every agent in the run uses it (see Model).

1. Compile the rough intent into a workflow (see *Compiling rough intent into a

workflow*): classify the job → pick the scale → pick the archetype → pick the pattern and name the failure mode it prevents → build the task contract → compose the phases → cast the personas → apply the standards. State the resulting assumptions to the user before authoring.

1. Author a workflow script from that compile (see Authoring). Write it into

the user's project so they can read and rerun it — ./.workflow.js, or workflows/.workflow.js / examples/harness-zoo// for a reusable harness. Scripts are plain JavaScript using only the injected globals (no imports).

1. Choose run settings (see Run defaults): --frontier, the effort flag for

the chosen scale (--auto-effort for a standard/deep harness, --effort medium for a quick one), a read-only sandbox unless the run must write, and a bounded --budget. For an expensive or complex workflow, --plan first — a no-token dry run that counts agents per phase/effort and estimates a --budget.

1. Run it — always pass --frontier, plus the effort flag for the chosen

scale: --auto-effort for a standard/deep harness (it scales each agent's effort to its layer's parallel width, so lone synthesis/judge gates think hardest), or --effort medium for a quick harness (see Effort). --frontier pins every agent to the latest frontier model (see Model): ``bash node ~/.claude/skills/codex-workflows/runner/bin/run-workflow.js --frontier --auto-effort [other flags] # quick_harness: … --frontier --effort medium [other flags] ` Progress streams on **stderr**; the workflow's return value prints as JSON on **stdout**. Capture stdout for the result (… 1>/tmp/result.json) when it's large. To **watch the run live**, add --tui (live ASCII map in a new terminal window) and/or --gui` (live HTML viewer in the browser) — see Running → Live monitoring.

1. Surface the result to the user (see Output behavior) — summarize it,

mention the script path, and render the run's ASCII map inline in this conversation so they see the execution graph natively (no window to open): ``bash node ~/.claude/skills/codex-workflows/runner/bin/map-run.js --journal --no-color ` ( is the path the run logged as ✎ journal: …, default .workflow-journal/.jsonl.) Paste that output into your reply inside a `` `text `` block — it's the orchestrator → phase layers → agent grid → result DAG with per-agent model/effort/tokens/time and a one-line result snippet per agent. **Always use --no-color** inline (raw ANSI would render as garbage in chat). For **live, in-session** monitoring, run the workflow with runinbackground and re-render this snapshot a few times while it's in flight (running agents show as ⠋ … running…); for a smooth live *window* instead, add --tui/--gui` (see Running → Live monitoring).

The run also prints a one-line cost/reliability recap when it finishes. For a fuller breakdown — tokens by phase, the costliest/slowest agents, and any red flags (many nulls, an un-staged huge fan-out, default-effort cost) — run summarize-run on the journal and fold the highlights into your reply (see Summarize a run).

Do NOT call the native Workflow tool while using this skill. Authoring the script and running it through the CLI above is exactly what routes the work to Codex; invoking the native tool would spawn Claude subagents instead.

Fleet mode (--multi): launch, supervise, steer

When the user passes --multi (or asks for a fleet / several workflows at once), you are the operator of N concurrent runs — not a fire-and-forget launcher. You compile a fleet plan, launch every variant in the background, then run a supervision loop: poll status, answer gates, steer drifting workers, kill dead ends, fork promising leads, and synthesize at the end. The human sets policy once (goal, total budget, risk tolerance); you make the mid-run judgment calls the variants can't make for themselves.

1 · Compile the fleet plan

Decompose the intent into 2–4 variants and state the plan (variants, what each bets on, per-run budgets) before launching. Two axes, freely mixed:

• Similar — the same harness, different slices: split a big input across

runs via --args, or attack the same question from different starting hypotheses/seeds. One script + per-run --args + --run-id (so the journals don't collide), or N copies of the script.

• Diverse — different harness shapes betting on different theories of the

task: e.g. a loop_until_dry bug hunt vs an adversarial_verification sweep vs a sessionful_controller_loop investigation, all aimed at the same goal. One script per variant.

Split the user's overall budget across variants (status shows each run's spend against its ceiling). Size read-heavy fan-outs realistically using the existing GPT-5.5 measurements: an agent whose job is reading a repo/corpus costs ~400–600k tokens regardless of its effort tier — the input dominates, so --effort low does not make a sweep cheap, and --plan's per-effort estimate undercounts it (measured: four "low" sweeps = 2.1M, 525k each, vs a 150k/agent plan estimate). At xhigh — which --auto-effort gives every sessionful worker's turns (width 1) — a reading turn runs ~1–1.5M (measured: a walkthrough worker's first turn + one steer tripped a 2.5M ceiling). Budget ≈ readers × 500k + xhigh reading turns × 1.2M + non-readers × the plan estimate, with headroom. A tripped ceiling is recoverable (--resume replays the prefix free) but costs a supervision round-trip. Apply the Anti-overbuild rule to the fleet too: 2 well-differentiated variants beat 4 redundant ones — every variant must bet on something the others don't.

2 · Author for supervision

Every variant gets supervisor checkpoints — human() gates at the junctures where an outside judgment can redirect the run:

const directive = await human(
  `Round ${round} findings: ${summary}. Directive for next round?`,
  { id: `round${round}`, choices: ["continue", "stop"], default: "continue", timeoutMs: 240_000 })
if (directive === "stop") break
if (directive !== "continue") await worker.steer(directive)   // free text = a steer

This is the steer channel: a free-text answer is the directive, and the script applies it (session.steer(...), re-aiming the next round, narrowing scope). Place gates between rounds, before expensive phases, and on uncertainty. Defaults must be safe — an unanswered gate times out to its default and the run degrades hands-off, never hangs. (This rides the journaled human() channel, so a --resume replays answers instead of re-asking.)

3 · Launch — one directory per fleet, every run in the background

Variants share one directory (that's what fleet status supervises). Launch each with run_in_background, always with --interactive (it enables the answer channel headlessly):

node ~/.claude/skills/codex-workflows/runner/bin/run-workflow.js hunt-orm.workflow.js \
  --frontier --auto-effort --interactive --budget 1500000 1>hunt-orm.result.json
# same script, different slice → isolate with --run-id:
node …/run-workflow.js hunt.workflow.js --args '{"slice":"auth"}' --run-id auth --interactive …

4 · Supervise — the loop

Poll the fleet digest between other work (and promptly while gates may be pending — they time out to defaults). For long unattended stretches, add --notify-cmd at launch so a pending gate pushes instead of waiting to be polled (e.g. append $WORKFLOW_EVENT to a file you watch, or a macOS osascript notification):

node ~/.claude/skills/codex-workflows/runner/bin/fleet.js status    # --json to parse

(When the user wants to watch alongside you, add --watch for an in-place terminal redraw, or --html fleet.html --open for a card-per-run browser dashboard that auto-refreshes while runs are live.)

One line per run — state (running / completed / stopped / idle), phase + agent progress, tokens vs budget — plus an ⚠ line per condition needing you. React:

| Signal | Your move | |--------|-----------| | ⚠ waiting on [id] "question" | Decide with your full conversation context, then fleet.js answer --journal --id '' --answer '' (--answer-json for structured) | | ⚠ stalled (no activity past threshold) | Inspect its stderr/--gui; if hopeless, kill the background task, then rerun with --resume (completed agents replay at 0 tokens; sessionful workers re-attach to their threads warm) | | A run chasing a dead end | Kill its task; note why, fold the negative result into the synthesis | | A run onto something big | Fork it: copy the journal to a new name, point an edited/extended variant at it with --journal --resume — the unchanged prefix replays free and only the new direction spends tokens | | ⚠ at/over budget · stopped | Decide: resume the most promising with a higher --budget, or harvest what's journaled (summarize-run shows where the tokens went) |

5 · Harvest and synthesize

When all runs are terminal: read each run's result (.result.json or the stdout you captured), reconcile agreements/conflicts across variants, and report per-variant: what it bet on, what it found, what it cost (fleet.js status --json has tokens; summarize-run has the breakdown). Negative results from killed runs are findings too. To chain fleets, feed one run's result.json into the next launch's --args-file — composit

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: scasella
• Source: scasella/claude-dynamic-workflows-codex
• License: MIT

Install and usage instructions live in the source repository linked above.