Use the version-pinned npm entrypoint below. A Codex plugin install loads skills
and MCP configuration, but it does not add the great-cto npm binary to PATH.
Do not imitate Claude Code hooks or manually chain roles: the controller reads
shared/pipeline.toml, persists the cursor and owns every write and gate
transition.
Preflight
npx --yes great-cto@3.62.0 codex-host doctor
npx --yes great-cto@3.62.0 codex-host list --dir /absolute/project
doctor.state=blocked means do not start. Docker may be unavailable when no
checks/release policy is requested; GitHub CLI may be unavailable when the local
adapter is used. The run store must not be group/world accessible.
For mixed-host runs, also require doctor.checks.claude.state=available.
Start
Policies must be operator-owned absolute files outside the worker project. Allowed paths are explicit controller write boundaries.
npx --yes great-cto@3.62.0 codex-host start \
--dir /absolute/project \
--prompt "the requested outcome" \
--allow src,tests,docs \
--checks-policy /absolute/operator/checks.json \
--release-policy /absolute/operator/release.json
Read the returned status, pending and release object. Never treat exit 2 as
success: it means a gate, manual action or blocked evidence requires attention.
Since 3.47.0, independent
graph roles can run on both hosts with
--routes qa-engineer=claude-code,security-officer=codex on start. The
controller dispatches only a symmetric join pair concurrently, checks both
proposals for overlap, serializes writes and runs the existing verifier and
human gates. The route map is fixed for the run. An interrupted wave must be
inspected; never start replacement workers against an uncertain wave.
Gates and recovery
Show the operator the exact gate/release summary and wait for explicit approval. Then pass back the controller-issued token; never synthesize or persist one in a project file.
npx --yes great-cto@3.62.0 codex-host approve RUN_UUID --token GATE_TOKEN
npx --yes great-cto@3.62.0 codex-host approve-release RUN_UUID --token RELEASE_TOKEN
npx --yes great-cto@3.62.0 codex-host resume RUN_UUID
Use recover only after inspecting the recorded reason. Recovery reuses the
same candidate and refuses unknown partial writes. cancel revokes unexecuted
approval but does not delete external audit evidence.
Release boundary
The local and GitHub Release adapters publish immutable artifacts and declare
activation: none. They do not deploy traffic. Local rollback means selecting
a previous directory; GitHub rollback is a newly gated superseding release.
Production activation needs a separate adapter and approval contract.
Detailed policy schemas and limitations are in docs/HOST-CODEX.md.