ultracodex

Run Claude Code workflow scripts, unmodified, on your Codex subscription — and on OpenCode. Then go further than running them: loop them until a skeptical verifier approves, schedule them with cron doing the waking, or stand up a permanent organization of agents that remembers. Your Claude session writes the script and reads the verified result; the heavy lifting lands on the subscription you aren't rationing.

The idea underneath: the agent is a unit of programming. You write ordinary JavaScript and call an agent like a function — await agent(prompt, { schema }) hands back a structured result. ultracodex abstracts the backend away, so one script runs on any of the three it supports: Codex, Claude, or OpenCode. Workflows, loops, schedules, and orgs are what you build once the agent is something you can program with.

Getting started is quick because your agent does the learning: a bundled skill teaches your coding agent how to drive ultracodex, so you describe the task and your agent writes and runs the workflow. One command installs it for Claude Code (ultracodex sync-skills); docs/skills.md covers codex, opencode, and any other agent. Given only that skill, a fresh agent ran all four pillars across Codex, Claude, and OpenCode (the numbers).

Quickstart

Prerequisites: Node ≥ 20, the Codex CLI installed and authenticated (codex login; tested against codex-cli 0.144.0), and — for the prompt-driven flow below — a driving agent, typically Claude Code. No driving agent handy? Skip to driving from the CLI. OpenCode is optional (tested against 1.17.18) — one [route] line turns it on.

npm install -g ultracodex      # or: pnpm add -g ultracodex
ultracodex doctor              # checks node, codex, auth, config — with actionable next steps
ultracodex sync-skills         # teaches Claude Code (and opencode) the whole contract

Then, in Claude Code, the prompt is just the task:

Write a haiku that survives three rounds of adversarial critique. Run it with ultracodex.

Claude authors the workflow, the fleet executes on Codex (watch it live with ultracodex ls / attach <runId>, or bare ultracodex for the TUI), and the verified result lands back in your Claude session.

Driving from the CLI works the same way. run takes a path to any Agent Script you've written, or a packaged workflow by name — the two that ship in the box are goal and loop:

ultracodex run goal --budget 200k --args '{"task":"Write a limerick about cron jobs.","criteria":"5 lines, AABBA, mentions crontab, actually funny."}'

The example scripts live in the repo (examples/) once you've cloned it (see From source); from a clone, ultracodex run examples/actor-critic-loop/workflow.js --watch --budget 200k runs one directly.

Run from your project's root — agents work in your cwd. --json blocks and prints the result (the machine path a driving LLM calls); --watch streams events; --detach prints the runId and exits; --budget takes output tokens (500k, 1m). Runs are detached processes over plain files: quit the terminal, nothing dies.

Workflows

Workflows scale what agents can take on. One script fans a task out to a fleet — parallel reviewers, pipelined stages, phased builds — and returns one verified result to whoever asked.

https://github.com/user-attachments/assets/4a7366cd-429c-4581-9703-7c28a9605c0e

The workflow pillar, live. One prompt — "Write an essay on the meaning of life — actor–critic loop, 3 rounds. Run it with ultracodex." — Claude (left) authors the script, Codex executes it, the TUI (right) watches, and the result lands back in Claude. (HD video)

A script is an ES module: a pure-literal meta export, then a plain-JS async body over eight injected globals. No imports, no TypeScript.

export const meta = {
  name: 'review-files',
  description: 'Fan out reviewers, verify findings, report',
  phases: [{ title: 'Review' }, { title: 'Verify' }],
}

const FILES = args?.files ?? ['src/auth.ts', 'src/api.ts']

phase('Review')
const findings = (await parallel(FILES.map(f => () =>
  agent(`Review ${f} for bugs. Return via the schema.`, {
    label: `review:${f}`,
    schema: { type: 'object', properties: { bugs: { type: 'array', items: { type: 'string' } } }, required: ['bugs'] },
  })
))).filter(Boolean)                    // failed agents are null, never throws

phase('Verify')
const verified = await pipeline(       // no barrier — each item flows independently
  findings.flatMap(f => f.bugs),
  (bug) => agent(`Try to refute: ${bug}`, { label: 'verify' }),
  (verdict, bug) => ({ bug, verdict }), // verdict may be null (failed verifier) — check it
)

return { verified: verified.filter(v => v && v.verdict) }

agent() opts: label (display + routing), phase, schema (JSON Schema), model / effort (advisory tiers, mapped in config), isolation: 'worktree', agentType (config profile, e.g. read-only explorer). parallel() is breadth, pipeline() is flow, and plain-JS while/for is depth. The full normative definition is docs/agent-script-spec.md; ultracodex validate --strict checks that a script stays in the portable subset that runs identically under Claude Code's Workflow tool and ultracodex.

Everything needed to author these — or to teach any model to author them — ships in the box: the authoring skill (one self-contained document, hardened against three model families; GPT-5.5 given only this file authored scripts judged comparable-or-stronger than Claude-written references on 7/7 problems) and the examples gallery (nine orchestration shapes ordered as a complexity ladder, distilled from a census of 58 real production workflows). Installing the skills into Claude Code, codex, opencode, or a raw prompt: docs/skills.md.

Loops

Loops scale how long agents keep at it. The stop condition moves out of your code and into a judgment: keep going until a skeptical verifier approves, until discovery runs dry, until a scheduled run reports done.

ultracodex run goal --args '{
  "task": "Implement the CSV import endpoint",
  "criteria": "Build passes. Tests pass. Malformed rows are rejected with row-level errors."
}' --budget 250k

The builder works in rounds; a separate verifier checks every criterion against the work itself and rejects until it holds. The TUI folds the rounds into a trajectory — ✖ ✖ ✔ · converged after 3 rounds — with per-round token cost, so convergence is something you watch. Loops are plain JavaScript while/for in any script; the packaged goal ships in the box (builds until approved — completion criteria like "the backlog is empty" work too); budget is the governor and pause/skip/stop work live. → docs/loops.md

Scheduler

The scheduler runs workflows on your clock.

ultracodex schedule add digest --every 30m --budget 200k -- run digest.js
ultracodex schedule add nightly --daily 18:30 --until-done --budget 300k -- run goal --args '…'

schedule add writes one tagged crontab line and owns it completely; there is no daemon. --until-done retires a schedule the day its workflow returns { done: true }. --budget caps every scheduled run — and scheduling a run without one gets a loud warning, because an unattended loop with no ceiling can drain a quota overnight. The Schedules tab shows exec-history strips, next-fire countdowns, and a run-now key. → docs/schedule.md

Orgs

Orgs scale what agents remember. This pillar ships as experimental — the runtime is tested and the acceptance org is real, but the discipline is young; supervise early cycles.

One analyst can't cover five hundred stocks. A research desk can: one analyst per name, each keeping their own notes, each writing a one-page brief their lead actually reads. An org is that desk, built from agents.

An org is a directory tree. Each agent is a directory — a role contract, its own memory files, an inbox — an