Codex Workflows Server

CI License: MIT Buy me a coffee

Codex has subagents, skills, plugins, and MCP. codex-workflows connects those pieces into a workflow-as-code runtime: durable multi-agent runs, a live terminal dashboard, restartable agents, saved workflow scripts, and review templates that are meant to be used on real repos.

This is not a native Codex /workflows command. Codex does not expose that plugin API today. This project ships the closest available surface: a Codex plugin with an MCP server and a cwf terminal UI.

Install

Install it from the GitHub marketplace in this repo:

codex plugin marketplace add robzilla1738/Codex-Workflows
codex plugin add codex-workflows@codex-workflows

Start a new Codex thread after installing. Then ask:

Use codex-workflows to run the bug-sweep workflow with adapter auto.
Open the live dashboard automatically and tell me the run id and status.

Codex will call the bundled MCP server. The server starts the workflow, opens the live TUI in your default terminal, and returns a run id you can inspect from Codex or from the CLI.

What it includes

• bug-sweep: bounded codebase review, adversarial verification, repro planning, and synthesis.
• bug-sweep-deep: larger opt-in fanout for deeper bug hunts.
• release-diff-review: release-blocker review against a branch or diff.
• security-auth-review: auth, permission, injection, secret, sandbox, and MCP boundary review.
• Live dashboard with phases, agent rows, token/tool/time metrics, recent worker activity, detail view, pause/resume/stop/restart/save controls, and final report path. Token totals show as pending until Codex emits usage metadata; command/tool/message/stderr activity updates as events arrive.
• Workflow definitions can explicitly request up to 64 concurrent workers and 2000 total agents.
• Durable run state under ${CODEX_HOME:-~/.codex}/codex-workflows/projects/<project-hash>/runs/<run-id>/ by default, so read-only bug hunts do not dirty the target repo.
• Project-local storage remains available with storageScope: "project" or --storage-scope project.
• Downstream verify, probe, and synthesize agents receive prior phase findings as explicit context instead of guessing at earlier results.
• Detached worker heartbeats let status reads and dashboards identify orphaned runs when a background workflow process dies.
• Isolated workflow script loading through QuickJS. Workflow scripts define phases and agent prompts; they do not get direct filesystem, shell, network, process, or Node built-in access.

Model controls

You can route models globally or by phase/agent:

Use codex-workflows to run bug-sweep with adapter auto,
model gpt-5.5, reasoning xhigh,
and modelMap {"find":"gpt-5.4-mini","synthesize":"gpt-5.5"}.

Caller overrides win over workflow defaults:

• model: default worker model.
• reasoning: default Codex reasoning effort.
• modelMap: phase id, agent id, or phase:agent overrides.
• promptSuffix: extra instruction appended to every worker.

Model names are validated against the local codex debug models catalog before any agents launch. Short names such as 5.4-mini are rejected with a suggestion like gpt-5.4-mini; they are not silently rewritten.

Bug-finding workflows default to read-only workers unless a workflow explicitly declares otherwise.

Local development

pnpm install
pnpm validate:plugin
pnpm test
pnpm cwf validate workflows/bug-sweep.workflow.js
pnpm cwf run workflows/bug-sweep.workflow.js --watch --adapter simulate
pnpm cwf run workflows/bug-sweep.workflow.js --watch --adapter auto --model gpt-5.4-mini
pnpm cwf run workflows/bug-sweep-deep.workflow.js --watch --adapter auto --model gpt-5.4-mini

Useful local commands:

pnpm cwf workflows
pnpm cwf watch <run-id>
pnpm cwf pause <run-id>
pnpm cwf resume <run-id>
pnpm cwf stop <run-id>
pnpm cwf stop-agent <run-id> <agent-id>
pnpm cwf restart-agent <run-id> <agent-id>
pnpm cwf save <run-id> --name release-diff-review-v2

The generated plugin lives at plugins/codex-workflows. Do not edit the bundled dist files by hand. Change the TypeScript packages, then run:

pnpm validate:plugin

That builds the packages, regenerates the plugin bundle, and checks that no machine-local paths leaked into the distributable plugin.

Plugin layout

.agents/plugins/marketplace.json
plugins/codex-workflows/
  .codex-plugin/plugin.json
  .mcp.json
  dist/
  skills/codex-workflows/SKILL.md
  workflows/*.workflow.js

The plugin bundle is committed so users can install from GitHub without running pnpm install.

Docs

• Plugin distribution
• Architecture
• Claude workflows parity analysis

Support

If this saves you time, you can support the project here: buymeacoffee.com/robcourson.