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

How it works in practice

Imagine asking Codex to build a new product surface.

1. A task starts

The SessionStart hook registers the task id, active profile, working directory, and the root model slug reported by Codex. It injects the exact task id into agent context; it does not read the transcript.

2. 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.

3. A stage resolves to a role and route

Profiles 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

4. The route runs

• A root route keeps the stage in the current task.

• An agent route launches a bounded subagent with the exact configured type, model, effort, service tier, and context-forking 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.

5. 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.

6. 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.

Architecture

flowchart LR
    U["User request"] --> R["Accountable root agent"]
    R --> S["Stage orchestration skill"]
    S --> C["Local MCP control plane"]
    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.

• 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 it.

3. Ask: “Show my current orchestration profile and live model evidence.”

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 profile is intentionally safe: every role stays on the root until you configure it.

Use natural language in Codex:

1. Inspect: “Show the active orchestration profile, every stage role, and current evidence.”

2. Create: “Create a profile called specialists based on balanced.”

3. Configure: “Route planning to model model-planning, design to model-design, development to model-development, and review to model-review.”

4. Test safely: “Keep this profile in observe mode and use it only for this task.”

5. Promote later: “After I confirm, make specialists the default for future tasks.”

Persistent configuration tools require explicit confirmation. The agent cannot silently change a shared profile or future-task default.

Profiles, roles, and routes

The standard stages are:

Route types

Keep a role on the current task 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 strings. The plugin never guesses an id or claims it is available before Codex accepts or observes a launch. See the complete generic example at examples/profiles/specialists-observe.json.

Current task versus future tasks

This separation makes it possible to change future behavior from inside any current Codex conversation without retroactively moving unrelated conversations.

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:

• Profiles, stage mappings, and routing fields.

• 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.

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 in version 0.1.

• No macOS menu-bar application.

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

• The model catalog is host-owned; configured ids are validated only as strings until Codex accepts or observes 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. A future MCP App can provide a richer visual surface over the same evidence ledger without changing its trust semantics.

Development

The runtime has no third-party package dependencies.

npm ci --ignore-scripts
npm run check

Validation covers profile schemas, persistence, current/future scope, 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 profiles with explicit review.

• Explore an optional MCP App status view where supported.

• Stabilize the state migration contract for 1.0.

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

License

MIT © 2026 Stage Orchestrator Contributors.