Codex Stage Orchestrator

Why this exists

Different phases of a software task benefit from different roles and, sometimes, different models. But orchestration becomes untrustworthy when it cannot answer three basic questions:

1. What route was configured?

2. Did Codex accept that route?

3. Which model did the host actually report at runtime?

Codex Stage Orchestrator answers each question separately. It gives one root agent responsibility for the whole task, routes only the stages that benefit from specialization, and keeps a small local evidence ledger populated by Codex lifecycle hooks.

Related MCP server: Proof Mode

At a glance

One quiet card, inside Codex

The control surface lives where the work already happens. It is collapsed by default to one line—current stage, requested route, and strongest evidence—and expands only when you open it or ask Codex to open it.

When expanded, it exposes only the selected stage and chat-owned controls:

• Every Apply action changes this chat only. There is no global scope switch in the card.

• Opening is not enabling. A dormant chat shows one explicit enable button and otherwise remains inert.

• The base template is copied, not referenced live. Selecting another template replaces this chat's base snapshot while keeping explicit local overrides.

• Reusable-template changes stay conversational and explicit. They require confirmation and never rewrite an existing chat.

• No menu-bar app, daemon UI, account, or extra window. The bundled MCP server serves the card itself.

• No UI dependency. On hosts that do not render MCP Apps, every read and change remains available through the same conversational tools.

How it works in practice

Imagine asking Codex to build a new product surface.

1. A task starts dormant

The SessionStart hook registers the task id, records the working directory and root model slug reported by Codex, and injects the exact task id into agent context. Orchestration remains off. It does not copy a template, inspect unrelated agent launches, or read the transcript.

2. The user enables this chat

Only an explicit request or click enables orchestration. The plugin then freezes the selected base template for this chat and asks the local Codex app server for the current model catalog. No other chat, reusable template, provider credential, or Codex default changes.

3. The root chooses useful stages

The orchestration skill evaluates the request. A simple bug may need only development and verification. A new interface may benefit from planning, design, development, review, and verification. It does not create agents merely to prove orchestration is enabled.

4. A stage resolves to a role and route

Reusable templates and their chat-owned snapshots use a two-step mapping:

stage → role → route

For example:

planning     → planner   → agent:model-planning
design       → designer  → agent:model-design
development  → developer → agent:model-development
review       → reviewer  → agent:model-review
verification → verifier  → root

Before work begins, Codex shows a compact status update:

Orchestration · planning · planner → agent:model-planning · evidence: configured

5. The route runs

• A root route keeps the stage on the current chat's root agent.

• An agent route launches a bounded subagent with the configured execution binding, model intent, supported effort, optional service tier, and bounded context policy.

• A skip route deliberately omits the stage.

The root remains responsible for decomposition, task packets, integration, verification, and the final response. A subagent never owns the whole user request.

6. Hooks confirm what happened

The pre-tool hook records the requested routing fields and can reject mismatches in strict mode. SubagentStart records the agent id, type, and model slug reported by Codex. If the configured and observed values differ, status shows both and flags the mismatch.

7. The root integrates the result

When the stage finishes, the root checks the result, records a short non-sensitive outcome, moves to the next useful stage, and eventually returns one integrated answer to the user.

This is the central boundary: the plugin does not hot-swap the root model inside an existing task. A stage assigned to another model runs as a Codex subagent.

Model discovery and provider support

The plugin does not ship a static model list. On explicit enable or refresh, it initializes a short-lived local codex app-server connection and calls the official model/list method. It also checks bounded local agent definitions for an exact model-to-agent binding. The sanitized result is stored only in that chat and drives model suggestions, execution bindings, and the reasoning-effort selector.

This means the card can use every picker-visible model that the current Codex installation advertises, including:

• OpenAI models available through the user's Codex/ChatGPT authentication.

• OpenCode Go routes and other custom-provider models exposed by Codex.

• Newly added models and reasoning levels without waiting for a plugin release.

Important boundaries:

• The catalog reflects this Codex installation and account. The plugin cannot unlock a model, bypass plan or workspace policy, create provider credentials, or make a ChatGPT-only model routable in Codex.

• Picker visibility and subagent routing are different host capabilities. A stage can run on another model only when Codex advertises that model as a direct spawn_agent override or a local agent definition binds it. OpenCode Go router bindings are detected automatically when installed.

• A bound agent type owns its provider model. Some Codex hosts still require an accepted native model argument to bootstrap spawn_agent; that bootstrap value is never presented as the runtime model, and the lifecycle hook must observe the provider model before the card marks it active.

• Host-hidden entries are excluded from the normal card. Advanced callers may refresh with include_hidden: true, but hidden entries can be internal and are not guaranteed to support general agent work.

• If discovery is unavailable, manual opaque model ids still work. They remain unverified until Codex accepts or mechanically observes the route.

• A catalog match proves advertised availability, not execution. Only hook_observed proves which model the host reported at runtime.

Architecture

flowchart LR
    U["User request"] --> R["Accountable root agent"]
    R --> S["Stage orchestration skill"]
    S --> C["Local MCP control plane"]
    C -->|"model/list"| M["Local Codex app server"]
    C <--> L["Private evidence ledger"]
    S -->|"exact bounded route"| A["Codex subagent"]
    H["Lifecycle hooks"] -->|"runtime evidence"| L
    A --> R
    R --> U

See Architecture and Protocol for state transitions, locking, trust boundaries, and the complete MCP contract.

Installation

Requirements

• A Codex build with plugin and lifecycle-hook support.

• The codex executable available to the plugin process for live catalog discovery (manual ids remain available without it).

• Node.js 20 or newer available as node.

• Git, for marketplace installation and updates.

The package follows the official Codex plugin authoring and lifecycle hook contracts.

Install from GitHub

codex plugin marketplace add slegarraga/codex-stage-orchestrator
codex plugin add codex-stage-orchestrator@codex-stage-orchestrator

Then:

1. Review and trust the bundled hook definition when Codex asks.

2. Open a new Codex task so SessionStart can register its dormant chat id.

3. Ask: “Open my orchestration control card.” Viewing is read-only; choose Enable for this chat only when you want orchestration here.

Plugin hooks are not trusted automatically. Without hook trust, profile and stage configuration still work, but the plugin correctly reports runtime model evidence as unavailable.

Install from a local checkout

git clone https://github.com/slegarraga/codex-stage-orchestrator.git
cd codex-stage-orchestrator
codex plugin marketplace add .
codex plugin add codex-stage-orchestrator@codex-stage-orchestrator

First five minutes

The built-in balanced template is intentionally safe: every role stays on the root until you configure it.

Use natural language in Codex:

1. Open: “Open my orchestration control card.”

2. Enable: click Enable for this chat. Codex refreshes this chat's available models.

3. Choose a stage: select planning, design, development, review, verification, or delivery.

4. Set its route: keep it on the root, choose an advertised specialist model and supported effort, or skip it.

5. Apply and verify: the change stays in this chat; watch configured intent advance to hook-observed runtime evidence when the route runs.

Reusable templates are optional. You can create or edit one conversationally for later reuse, but persistent tools require explicit confirmation. The card itself never changes a reusable template or new-chat default.

Templates, roles, and routes

The standard stages are:

Route types

Keep a role on the current chat's root model:

{ "kind": "root" }

Launch a bounded Codex agent:

{
  "kind": "agent",
  "agent_type": "worker",
  "model": "model-a",
  "reasoning_effort": "high",
  "service_tier": "priority",
  "fork_turns": "none"
}

Explicitly skip a role:

{ "kind": "skip", "reason": "No visual surface in this workflow." }

Model ids are opaque route strings. The card prefers exact ids and efforts from the chat-local Codex catalog, while still allowing unlisted custom-provider ids. An advertised model is not claimed as executed until lifecycle evidence observes it. See the complete generic example at examples/profiles/specialists-observe.json.

Every chat is independent

The embedded card exposes only chat-owned operations. Persistent template operations remain available through explicit conversational tools with confirmation.

Evidence you can trust

Evidence never moves backward. A late acceptance event cannot replace an earlier hook observation, and agent self-identification is never treated as proof.

Observe versus strict

Strict matching checks every configured routing field. It cannot rewrite a tool call, so the root must pass the exact route. Route verification errors remain fail-open by default; advanced users may set STAGE_ORCHESTRATOR_FAIL_CLOSED=1 after validating local state.

Privacy and local state

By default, state lives at $CODEX_HOME/stage-orchestrator or ~/.codex/stage-orchestrator. Set STAGE_ORCHESTRATOR_DATA_DIR to isolate it.

Stored:

• Reusable templates plus each chat's independent snapshot, stage mappings, and routing fields.

• A sanitized per-chat model catalog: ids, display names, advertised efforts/modalities, provider labels, optional agent-type bindings, and refresh time.

• Task/session ids, working directory, agent ids, and timestamps.

• Stage transitions and hook-reported model slugs.

• A small capped evidence and event history.

Never read or stored:

• Transcript contents or transcript paths.

• Prompt bodies or agent task packets.

• Agent messages, generated work, or final answers.

• Shell commands, patches, file contents, browser data, or unrelated tool inputs.

• Provider API keys, bearer tokens, auth commands, or general Codex configuration contents. On explicit catalog refresh, only top-level name and model strings are read from bounded local agent-definition files to resolve exact execution bindings.

Files use private permissions where supported. Writes are atomic, session filenames are hashed, and cross-process locks protect concurrent hook/MCP updates. See Security.

Product boundaries

• No in-place root-model hot swap; specialization uses bounded subagents.

• No native badge injected into the Codex task header.

• No macOS menu-bar application.

• Installed does not mean active: every chat starts off and unrelated agent launches remain untouched.

• The optional embedded MCP App is collapsed by default and never required for core operation.

• Live status appears through the card where supported, lifecycle state, MCP results, Codex agent surfaces, and concise orchestration commentary.

• The model catalog is host-owned and discovered dynamically; catalog presence is advertised availability, while execution still requires acceptance and hook evidence.

• Direct subagent model overrides remain host-owned. Provider models with installed local agent bindings use those bindings automatically; unbound entries stay selectable but unverified until Codex accepts them.

• Hook trust and a new task are required for runtime evidence after installation.

These constraints are explicit so the plugin remains honest across Codex hosts. The card is a view over the same evidence ledger; it does not change routing or trust semantics.

Development

The runtime has no third-party package dependencies.

npm ci --ignore-scripts
npm run check

Validation covers opt-in activation, live catalog protocol and pagination, model-specific effort checks, template schemas, frozen chat snapshots, strict enforcement, evidence monotonicity, runtime mismatches, hook privacy, cross-process locking, MCP stdio, and package structure. CI runs on Ubuntu, macOS, and Windows with supported Node.js versions.

Repository layout:

plugins/codex-stage-orchestrator/  Plugin manifest, MCP server, hooks, skill
examples/profiles/                 Generic example profiles
docs/                              Architecture, protocol, and Spanish guide
test/                              Node test suite
.agents/plugins/marketplace.json   Git-backed Codex marketplace catalog

Contributing and support

Contributions are welcome. Please read Contributing and the Code of Conduct, search existing issues, and include tests for protocol or persistence changes.

• Questions and ideas: GitHub Discussions

• Bug reports and feature requests: GitHub Issues

• Security concerns: follow the private process in SECURITY.md

• General help: SUPPORT.md

Roadmap

• Gather compatibility evidence across Codex desktop and CLI releases.

• Add import/export for reusable templates with explicit review.

• Expand MCP App compatibility evidence across supported Codex hosts.

• Stabilize the state migration contract for 1.0.

• Submit to the public Plugins Directory after real-world validation.

License

MIT © 2026 Stage Orchestrator Contributors.