| name | ultracodex |
| description | Author and run multi-agent Agent Script workflows on the OpenAI Codex CLI (and OpenCode) via the ultracodex runner. Use when the user asks to run a workflow with ultracodex, orchestrate parallel agents, fan-outs, pipelines, or builder-verifier loops, to schedule recurring agent runs, to stand up an agent org, or to offload multi-agent execution from Claude to Codex. |
ultracodex executes Claude Code Workflow-tool scripts unmodified, routing each agent() call to an OpenAI Codex (or OpenCode) session. This file is the complete contract — assume the ultracodex binary is installed and authenticated; do NOT explore the CLI with --help, inspect the repo, or run doctor first (only run ultracodex doctor if a command fails unexpectedly).
Choosing the shape
Default to authoring a workflow. The other shapes exist, and you should reach for them ONLY when the user's own words ask for what they do — recurrence, a packaged loop by intent, a standing org. When in doubt: a workflow.
| the user asks for | reach for |
|---|
| a task done — build, review, research, migrate | author a workflow (the default, including loop-shaped ones) |
| "keep iterating until it's good / until nothing is left", no bespoke roles | ultracodex run goal (packaged builder-verifier) |
| "every night / every 30m / keep it running on a schedule" | ultracodex schedule add wrapping a run |
| standing coverage of many subjects with memory that compounds | an org — experimental; only on explicit request |
If the request implies recurrence or standing coverage without saying so ("track X for me", "keep an eye on Y"), name the options — run once now, a budgeted schedule, or an experimental org — and let the user pick. Do not guess upward.
Authoring
Write the script EXACTLY as you would for the Workflow tool — same format, byte for byte: export const meta = {name, description, phases?} as a pure literal, then a plain-JS async body over the injected globals agent / parallel / pipeline / phase / log / args / budget / workflow. Loops are ordinary JavaScript (null-check every agent result; guard unbounded loops on budget). No imports, no TypeScript. Save it to a file.
Format reference, in priority order: if the Workflow tool's definition is in your context (the session has the tool), use that — it is the native, authoritative description and you already know the format. Otherwise, learn the format from the agent-script-authoring skill (installed alongside this one; also at skills/agent-script-authoring/SKILL.md in the ultracodex package).
Running
ultracodex run <file-or-name> --json [--budget 500k] [--args '<json>']
- Blocks until the run completes; stdout is the result JSON (the script body's return value). Non-zero exit = the run failed.
--budget is an output-token ceiling (integer, k/m suffixes).- Model/backend routing lives in
.ultracodex/config.toml, never in the script.
- Optional pre-check:
ultracodex validate <file> --strict. Fix ERRORS; WARNINGS are non-blocking — do not rewrite a working script just to silence a warning.
- Inspect a finished run with
ultracodex show <runId> — result, per-agent lines, and a round-by-round LOOPS trajectory for iterating runs. The human can watch live with ultracodex ls / attach <runId> — you do not need to poll.
The packaged loop
One reference loop ships in the package and resolves by name:
ultracodex run goal --json --budget 300k --args '{"task":"...","criteria":"explicit, verifier-checkable"}'
goal runs builder rounds gated by a skeptical verifier until the criteria hold (also: maxRounds, context, builderModel/verifierModel). The criteria carry the stop condition — completion works too ("the backlog is empty", "a fresh search finds nothing unlisted"). It returns { done: ... } — and any workflow that returns { done: true } composes with scheduled --until-done runs.
Scheduling
ultracodex schedule add <name> (--every 30m | --daily 18:30) --budget 200k -- run <workflow> [--args '<json>']
ultracodex schedule ls | pause <name> | resume <name> | rm <name>
One tagged crontab line per schedule, fully owned; there is no daemon. ALWAYS pass --budget on scheduled runs — an unattended loop with no ceiling can drain the user's quota (the CLI warns if you omit it). --until-done retires the schedule when the run returns { done: true }; --max-runs N caps repetition.
Orgs (experimental)
An org is a directory tree of agents with durable memory — one seat per subject, inboxes, tickets, briefs rolling up the tree — ticked by ultracodex org tick. Day-2 verbs, exactly these shapes: org status --json · org ask <seat> "<question>" (read-only fork) · org tick --json (no watch flag; it runs to completion) · org lint --json · org audit · org replay. To design one, use the org-creation skill (installed alongside this one). Treat the whole pillar as experimental — and SAY SO: whenever you set up or recommend an org, explicitly tell the user it is experimental, with young interfaces and disciplines, and that early cycles deserve supervision rather than unattended scheduling.
Results
Relay the run's stdout verbatim (then you may summarize it). If the run failed, report the failure as-is and stop — do NOT substitute your own answer for the workflow's work.
