Codex Workflows

What It Does

Codex Workflows is a workflow-as-code runtime for OpenAI's Codex CLI. It ships as a Codex plugin with an MCP server, a terminal dashboard (cwf), four built-in workflow templates, and a SKILL.md that guides the agent through the full lifecycle. Workflows are JavaScript files loaded inside a QuickJS sandbox (no filesystem, shell, network, or Node built-in access). They define phases, agents, prompts, and context-passing rules. The runtime then fans out up to 64 concurrent Codex subagents across those phases, collects structured JSON findings, and routes verified claims downstream to verification, probe, and synthesis phases. The project targets developers using Codex CLI who need repeatable multi-agent processes like codebase bug sweeps, release diff reviews, and security audits.

The Good

Thoughtful phase-to-phase context passing is the core differentiator. Unlike a simple fan-out where every agent works in isolation, Codex Workflows lets each agent declare contextFrom selectors that pull specific findings from prior phases. The bug-sweep workflow routes find-phase claims to verify agents by index (one claim per verifier), then routes all verified claims to probe agents for repro steps, and finally routes everything to a synthesis agent for a prioritized report. This is the right architecture for adversarial code review: later agents review concrete earlier claims instead of guessing.

QuickJS sandboxing of workflow scripts is a genuine security boundary. The definition loader (packages/runtime/src/definition.ts) runs workflow scripts inside QuickJS with require, process, Buffer, module, exports, global, __filename, and __dirname all set to undefined. Workflow scripts can only call workflow({...}) to define phases and agents. They cannot access the filesystem, spawn processes, or import modules. This matters because workflow files are user-authored JavaScript, and the sandbox prevents a malicious workflow from escaping its intended scope.

The test suite covers real workflows end to end. Seven test files with 28 passing tests cover schema validation, definition loading, model validation, store persistence, the CLI dashboard, adapter creation, and the full runner lifecycle. The runner tests (455 lines, 10 tests) verify pause, resume, stop, per-agent cancellation, failed agent recovery, and context routing. The CI pipeline runs typecheck, tests, plugin build, plugin validation, and a smoke test that validates and runs the bug-sweep workflow in simulate mode. This is above-average test discipline for an agent skill project at this stage.

The monorepo structure is clean and well-separated. Five packages (schemas, codex-adapter, runtime, cli, mcp-server) total 6,810 lines of TypeScript source. Each package has a single job: schemas define types with Zod, the adapter abstracts Codex invocation (simulate, exec, sdk), the runtime handles loading and scheduling, the CLI provides the dashboard, and the MCP server exposes 11 tools to Codex. There is no cross-contamination between packages, and the dependency graph is a clean tree.

The MCP server surface is comprehensive. Eleven tools cover the full workflow lifecycle: workflow_run, workflow_validate, workflow_preview, workflow_status, workflow_events, workflow_agent_detail, workflow_pause, workflow_resume, workflow_stop, workflow_stop_agent, workflow_restart_agent, workflow_save, and workflow_list. Every tool has a Zod input schema, and the server includes model validation that checks model names against the local codex debug models catalog before launching any workers.

The Bad

The project requires Codex CLI to deliver its primary value. Without a running Codex session with API access, the only functional adapter is simulate, which produces canned output. The MCP server runs over stdio and expects a Codex plugin host to start it. Users who want to try the tool on a non-Codex agent (Claude Code, Hermes, Amp) cannot use the MCP tools or real subagent execution. This is inherent to the product design, not a bug, but it limits the audience to Codex users specifically.

pnpm is required for local development but not globally available on macOS. The project uses pnpm@10.30.3 with workspaces. Developers who do not have pnpm installed globally need to install it first (npm install -g pnpm), and on macOS that frequently hits the EACCES permission error in ~/.npm/_cacache/. The workaround documented in the README (pnpm install after setup) does not address this. A note about using corepack enable or npm install -g pnpm would help.

The release-diff-review workflow has hardcoded references. The release-diff-review.workflow.js defines agents with specific model names ("Codex") and prompts mentioning "v1.1.2...main for Harness v1.2.0." This looks like it was written for a specific release review of a different project (Harness). While the workflow structure is reusable, the content is not generic. Users who install the plugin expecting a clean release-review template will need to rewrite the find-phase prompts. The bug-sweep and security workflows are generic and do not have this issue.

No published npm package or tagged release. The repo has a single commit, no git tags, and no npm publish history. Installation is through the Codex marketplace (cloning from GitHub) or local development. A tagged v0.2.0 release with a GitHub Release page would make version pinning possible and signal stability.

Smoke Test Results

All testing was done on macOS (aarch64) with Node 22, pnpm 10.30.3, after a fresh shallow clone.

Run A -- Fresh clone, pnpm install, build, test

$ cd /tmp && git clone --depth 1 https://github.com/robzilla1738/Codex-Workflows.git
Cloning into 'Codex-Workflows'...

$ cd Codex-Workflows && pnpm install
Done in 15.6s using pnpm v10.30.3

$ pnpm build
packages/schemas build: Done
packages/codex-adapter build: Done
packages/runtime build: Done
packages/mcp-server build: Done
packages/cli build: Done

$ pnpm test
Test Files 7 passed (7)
 Tests 28 passed (28)
 Duration 1.26s

Pass rate: 6 of 6. Clean install, build, and test with zero failures.

Run B -- Plugin CLI smoke test

$ node plugins/codex-workflows/dist/cli.js --version
0.2.0

$ node plugins/codex-workflows/dist/cli.js --help
Usage: cwf [options] [command]
Commands: validate, run, watch, workflows, pause, resume, stop,
 stop-agent, restart-agent, save

$ node plugins/codex-workflows/dist/cli.js validate workflows/bug-sweep.workflow.js --cwd /tmp
{"ok":true,"definition":{"name":"bug-sweep",...},"errors":[],"warnings":[]}

$ node plugins/codex-workflows/dist/cli.js validate workflows/security-auth-review.workflow.js --cwd /tmp
{"ok":true,...,"errors":[],"warnings":[]}

$ node plugins/codex-workflows/dist/cli.js validate workflows/release-diff-review.workflow.js --cwd /tmp
{"ok":true,...,"errors":[],"warnings":[]}

$ node plugins/codex-workflows/dist/cli.js run workflows/bug-sweep.workflow.js --cwd /tmp --adapter simulate --no-watch
2026-06-06T09-07-34Z-bug-sweep-1eb4c2

$ node plugins/codex-workflows/dist/cli.js workflows --cwd /tmp
Built-in workflows:
 workflows/bug-sweep.workflow.js
 workflows/bug-sweep-deep.workflow.js
 workflows/release-diff-review.workflow.js
 workflows/security-auth-review.workflow.js
Recent runs:
 2026-06-06T09-07-34Z-bug-sweep-1eb4c2 completed bug-sweep

Pass rate: 6 of 6. CLI installs, reports correct version, lists all subcommands, validates all 3 tested workflows, and completes a simulate run.

Run C -- Functional verification (simulated workflow execution)

The simulate adapter produces deterministic output for each agent based on the workflow definition. The completed run appeared in workflows output with status completed, confirming the full lifecycle (init, phase execution, agent scheduling, summary write) works. Real Codex subagent execution was not tested (requires Codex CLI + API key).

Functional pass rate: 2 of 3. CLI and workflow lifecycle verified. MCP server stdio transport and real Codex adapter not tested (requires Codex CLI environment).

What the runs tell you

The project builds and tests cleanly from a fresh clone. The CLI and simulate adapter work end to end, which means the runtime, store, and runner are all functional. The untested surface is the Codex adapter (exec, sdk, auto modes) and the MCP stdio transport, both of which require a Codex CLI environment that cannot be replicated without Codex installed and authenticated.

Setup Walkthrough

1. Install Codex CLI (if not already installed): follow OpenAI's Codex CLI docs.
2. Add the plugin from the marketplace:

codex plugin marketplace add robzilla1738/Codex-Workflows

codex plugin add codex-workflows@codex-workflows

1. Start a new Codex thread and ask:

Use codex-workflows to run the bug-sweep workflow with adapter auto.

1. For local development without Codex:

git clone https://github.com/robzilla1738/Codex-Workflows.git

cd Codex-Workflows && pnpm install && pnpm build && pnpm test

1. Run a dry workflow in simulate mode:

node plugins/codex-workflows/dist/cli.js run workflows/bug-sweep.workflow.js --cwd /path/to/your/project --adapter simulate --no-watch

Post-install gotcha: pnpm is not pre-installed on most macOS systems. Use corepack enable or npm install -g pnpm before the local dev steps. If you hit EACCES errors in ~/.npm/_cacache/, use sudo chown -R $(whoami) ~/.npm or install pnpm via Homebrew (brew install pnpm).

Alternatives

1. obra/superpowers -- a Hermes skill pack with subagent-driven development patterns. Broader agent compatibility but no dedicated workflow runtime or TUI dashboard.
2. Claude Code workflows -- Claude Code has native subagent support but no formal workflow-as-code definition format. Codex Workfills fills this gap for Codex specifically.
3. Manual multi-prompt Codex sessions -- running multiple Codex threads by hand and synthesizing results manually. Free but time-consuming and not reproducible.