Codex Stage Orchestrator

<p align="center"> <strong>Stage-aware, evidence-backed model routing for Codex.</strong><br> Assign planning, design, development, review, verification, and other stages to explicit roles—without losing root-agent accountability or pretending a requested model actually ran. </p>

<p align="center"> <a href="https://github.com/slegarraga/codex-stage-orchestrator/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/slegarraga/codex-stage-orchestrator/actions/workflows/ci.yml/badge.svg"></a> <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a> <a href="package.json"><img alt="Node.js 20+" src="https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white"></a> <a href="https://github.com/slegarraga/codex-stage-orchestrator/releases"><img alt="Release" src="https://img.shields.io/github/v/release/slegarraga/codex-stage-orchestrator?display_name=tag"></a> </p>

<p align="center"> <a href="README.md">English</a> · <a href="docs/GUIA-ES.md">Español</a> </p>

[!IMPORTANT] This is an independent open-source project, not an official OpenAI product. Version 0.3.x is an early release: its chat-isolation, evidence, and safety contracts are deliberate, while MCP App rendering may vary across Codex hosts.

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.

At a glance

Capability	Behavior
Stage routing	Maps discovery, planning, design, development, review, verification, and delivery to logical roles.
Role routing	Keeps a role on the root, launches an exact Codex subagent route, or explicitly skips it.
Chat-owned configuration	Gives every chat an independent routing snapshot that no other chat can mutate.
Reusable templates	Copies a reviewed template into a chat at startup or on explicit activation; later template edits cannot leak back.
Quiet control card	Shows stage, route, and evidence in a collapsed-by-default MCP App inside Codex.
Live evidence	Records root and subagent model slugs mechanically reported by lifecycle hooks.
Enforcement	Observes mismatches by default; optionally denies mismatched agent launches in strict mode.
Privacy	Never reads transcripts or stores prompts, agent messages, generated work, or unrelated tool inputs.
Runtime	Dependency-free Node.js MCP server and hook handler.

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

The SessionStart hook registers the task id, copies the complete default template into a chat-owned snapshot, records the working directory and root model slug reported by Codex, and 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

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

4. 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 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: “Open my orchestration control card.” If the host does not render MCP Apps, ask for the same status conversationally.

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. Choose a stage: select planning, design, development, review, verification, or delivery.
3. Set its route: keep it on the root, choose a specialist route, or skip it.
4. Apply: the change is written only to this chat.
5. Verify: 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:

Stage	Default role	Typical purpose	Required by default
discovery	researcher	Inspect unknowns and gather bounded evidence.	No
planning	planner	Decide scope, architecture, sequence, and acceptance criteria.	Yes
design	designer	Make UX, visual, interaction, or artifact decisions.	No
development	developer	Implement the approved work.	Yes
review	reviewer	Independently inspect correctness, quality, and risk.	Yes
verification	verifier	Run proportionate tests and validate the visible outcome.	Yes
delivery	release_manager	Package, publish, or hand off a verified result.	No

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

Every chat is independent

User intent	Scope	Result
“Use specialists here.”	This chat	Copies specialists into this chat; no live shared reference remains.
“Use the root for build here.”	This chat	Adds a chat-owned stage override without editing any template.
“Make this chat strict.”	This chat	Changes enforcement only for this chat.
“Change the developer route in specialists.”	Reusable template	Changes later copies only; every existing chat keeps its snapshot.
“Make specialists my default.”	New chats	New chats copy it at SessionStart; existing chats remain untouched.

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

Evidence you can trust

Evidence	What it proves	Runtime identity?
configured	A validated profile selected the route.	No
route_requested	A spawn_agent call reached the pre-tool hook.	No
route_accepted	Codex accepted the route or returned an agent id.	Not yet
hook_observed	A lifecycle hook mechanically reported the active model slug.	Yes
failed	The route or stage failed.	Failure state

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

Mode	Mismatched launch	Recommended use
observe	Records the mismatch and allows Codex to continue.	Initial setup, experimentation, and compatibility testing.
strict	Denies a mismatched spawn_agent call.	Stable, audited profiles where exact routing matters.

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.
• 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.
• No macOS menu-bar application.
• 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; 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. 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 template schemas, frozen chat snapshots, legacy-session migration, 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.