Codex Workflow Governor

A native OpenAI Codex plugin for asynchronous multi-agent workflow orchestration.

Codex Workflow Governor turns codex exec into reviewed, reproducible task graphs. Run parallel agents with bounded fan-out, compose reusable workflows, validate strict JSON outputs, preview templates before writing them, detach long-running jobs, compile adaptive research waves, and operate durable monitoring loops from the Codex CLI or a local MCP server.

The runtime uses only the Python standard library—no OpenAI Agents SDK, LangGraph, CrewAI, Temporal, hosted service, or separate API key.

Contents

• Why use it?
• Quick start
• First successful workflow
• Choose the right execution model
• Who should not install it?
• Requirements
• Install, update, or remove
• Operator documentation

Why use it?

• Parallelize safely: bound concurrency, model calls, retries, and deadlines.
• Build real DAGs: connect tasks through validated outputs instead of shared conversation state.
• Recover durable work: inspect, resume, pause, or cancel detached finite, adaptive, and recurring runs.
• Fail closed: reject malformed artifacts, stale process identities, permission drift, and false completed states.
• Reuse reviewed workflows: install built-ins or version project definitions and pinned Codex agents.
• Use Codex-native surfaces: invoke four skills, one CLI, or 17 typed local MCP tools over one engine.

Capability	Best for
Finite workflow DAGs	Parallel analysis, review, fan-out/fan-in, composition, and structured synthesis
Prompt-compiled adaptive runs	Research where later work depends on observed evidence gaps
Persistent loops	Bounded monitors and recurring issue-processing workflows
Project agents v2	Byte-pinned custom Codex roles with drift and permission checks
Reviewed authoring	Semantic presets and byte-exact workflow/agent preview→apply transactions
Documentation quality	Markdown scoring, topology checks, and isolated draft optimization
Local MCP	Discovery, authoring, execution, lifecycle, results, events, and optional native Tasks for authorized Git worktrees

Quick start

codex plugin marketplace add BearsCLOUD/codex-workflow-governor --ref main
codex plugin add codex-workflow-governor@bears-workflow-governor
codex plugin list

Restart Codex. Ask it to use $codex-workflow-governor:codex-workflows for a parallel task graph, adaptive research run, or durable monitor.

Agents start from the live catalog instead of guessing definitions:

python3 skills/codex-workflows/scripts/codex_workflows.py \
  --project-root "$PWD" workflow catalog --json
python3 skills/codex-workflows/scripts/codex_workflows.py \
  --project-root "$PWD" workflow describe builtin:fanout-synthesize --json

The bundled catalog includes general fan-out and review graphs plus quality-gate, engineering-delivery, and read-only incident-triage workflows. Project templates are created with single, review, fanout, or composite presets; every preset emits strict schemas and example inputs.

First successful workflow

From a cloned checkout, run the bundled read-only fan-out example. It performs two independent analyses in parallel and then synthesizes them.

CLI=skills/codex-workflows/scripts/codex_workflows.py
cat > /tmp/governor-inputs.json <<'JSON'
{
  "items": [
    "Option A: run independent checks in parallel.",
    "Option B: run every check sequentially."
  ],
  "request": "Recommend an execution option for independent checks."
}
JSON

RUN_ID=$(python3 "$CLI" --project-root "$PWD" run builtin:fanout-synthesize \
  --inputs /tmp/governor-inputs.json --detach)
python3 "$CLI" --project-root "$PWD" wait "$RUN_ID" --timeout 300
python3 "$CLI" --project-root "$PWD" result "$RUN_ID"

Expected terminal shape; model wording may vary:

exec_...  completed  fanout-synthesize
  calls: active=0 queued=0 completed=3 failed=0 blocked=0
  analyze-items: completed completed=2/2 active=0 queued=0
  synthesize: completed

The final JSON contains status: "success", source_items: 2, the recommendation, key findings, conflicts, and unresolved assumptions. This exact three-call lifecycle is validated by the release gates.

Choose the right execution model

Option	Choose it when	Do not choose it when
Workflow Governor	Work needs a reusable DAG, bounded parallelism, strict schemas, detached execution, or restart recovery	One direct call is enough
Direct codex exec	The task is isolated, short, and needs no reusable graph or persisted lifecycle	Multiple dependent calls need coordination
Normal Codex subagents	A live parent agent can delegate bounded work and keep ownership in the current task	Work must survive the parent session or expose durable checkpoints
Another orchestration plugin	You specifically need its hosted UI, cross-provider routing, managed scheduler, or domain workflow	You need Governor's local, standard-library, strict-artifact model

Governor complements normal subagents: subagents are a delegation mechanism; Governor is a persisted workflow runtime with explicit contracts. Evaluate other plugins by their actual permissions, persistence, recovery, data handling, and installation model rather than feature count alone.

Who should not install it?

Do not install Governor when:

• all work is one isolated codex exec call;
• you want a hosted dashboard, cloud queue, OAuth service, or cross-provider model router;
• you cannot run Linux with Python 3.11 or newer;
• you do not need strict JSON schemas, durable artifacts, checkpoints, or bounded fan-out;
• repository-local workflow files and explicit permission review are more process than the task warrants.

Requirements

• Linux with Python 3.11 or newer;
• a current Codex CLI authenticated with codex login;
• a Git worktree for workflows allowed to modify a repository.

The runner reuses the Codex CLI login and requires no separate API key.

Install, update, or remove

# Inspect the installation and local MCP registration
codex plugin list
codex mcp get workflow-governor-local --json

# Update the Git marketplace snapshot, then reinstall
codex plugin marketplace upgrade bears-workflow-governor
codex plugin add codex-workflow-governor@bears-workflow-governor

# Remove
codex plugin remove codex-workflow-governor@bears-workflow-governor

Start a new Codex process after installation or update so it loads the new skills and MCP server.

Operator documentation

• Operator guide: 17-tool MCP operation, native Tasks, reviewed authoring, finite DAGs, persistent loops, adaptive runs, and pinned project agents.
• Workflow format: definition, task, permission, and output contracts.
• Authoring and discovery: live catalog, focused describe, presets, and dry-run review.
• Composition: wait/background child calls, structured concurrency, limits, and recovery.
• MCP operations: 17 tools, reviewed writes, pagination, native Tasks, and protocol fallback.
• Prompt workflows: adaptive compilation and restart lifecycle.
• Loop workflows: checkpoint, control, and crash recovery.
• Security boundary and support routes.

Security and support

Repository content, workflow inputs, and upstream model outputs are untrusted data. Runtime state uses private directories and files, but operating-system isolation and the Codex sandbox remain the enforcement boundary. Never pass credentials or unnecessary personal information as workflow inputs.

Use GitHub Discussions for usage help, GitHub Issues for reproducible defects, and private vulnerability reporting for security issues.

License

MIT. See LICENSE.