codex-orchestrate
/codex-orchestrate
Claude Code only. Use when the user explicitly invokes /agents-bridge:codex-orchestrate (or /codex-orchestrate) in Claude Code or asks Claude to orchestrate a large multi-slice plan by delegating implementation to the Codex CLI through agents-bridge. In native Codex, use $slice-runner instead.
- Author
- bengous ↗
- Repository
- claude-code-plugins ↗
- Licence
- MIT
- Last repository change
- 20.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Claude Code only. Use when the user explicitly invokes /agents-bridge:codex-orchestrate (or /codex-orchestrate) in Claude Code or asks Claude to orchestrate a large multi-slice plan by delegating implementation to the Codex CLI through agents-bridge. In native Codex, use $slice-runner instead.
Original author description
Claude Code only. Use when the user explicitly invokes /agents-bridge:codex-orchestrate (or /codex-orchestrate) in Claude Code or asks Claude to orchestrate a large multi-slice plan by delegating implementation to the Codex CLI through agents-bridge. In native Codex, use $slice-runner instead.
How it works
- Principle
- Model routing per slice
- Pre-flight
- Loop per slice
- Codex prompt template
- Invocation mechanics
- Failure protocol
- Known pitfalls (lived)
SKILL.md preview
---
name: codex-orchestrate
description: Claude Code only. Use when the user explicitly invokes /agents-bridge:codex-orchestrate (or /codex-orchestrate) in Claude Code or asks Claude to orchestrate a large multi-slice plan by delegating implementation to the Codex CLI through agents-bridge. In native Codex, use $slice-runner instead.
---
# Orchestrating a plan in slices through Codex
Claude Code only. In native Codex, use `$slice-runner`.
## Principle
Claude is **architect, QA and committer**; Codex is **the executor**. Claude cuts
the plan into sequential slices, imposes the interfaces, starts one Codex run per
slice, checks the gates itself, and commits. Codex never commits and never
designs: if Claude lets Codex invent an API, N slices produce N styles.
## Model routing per slice
Pick the role when writing the slice's prompt:
| Slice | Role | Why |
|---|---|---|
| Standard code (features, wiring, specified refactor) | `coding` | **Default.** |
| Tests, mechanical fixes to pass a gate | `bounded` | Fastest and cheapest, enough for bounded work |
| Code that needs judgment or rigour, dense tricky points | `audit` | The highest ceiling |
`"${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.ts" models` prints the model and
effort behind each role and every effort each model supports. Hard decisions
(architecture, API choices) stay Claude's work — a slice that contains one is a
slicing defect, not a reason to move up a tier.
These models delegate well themselves: on a heavy slice, allow the prompt to
hand mechanical sub-parts to a cheaper model, rather than over-slicing on the
orchestrator's side.
**Context rule**: read a slice through the final message (Codex's summary),
`git diff --stat` and the gates, not through the run's full event stream or its
full diff: those land in your context at every slice and crowd out the plan.
Targeted inspection (grep, partial Read) only when a gate fails or the
slice has a risk named in advance in its prompt.
## Pre-flight
1. A plan the user validated, cut into slices: small, sequential, each with an
explicit exit gate (e.g. `validate` alone for internal wiring; + e2e/visual
for what touches the DOM).
2. **Slice 0 = baseline**: every gate green before the first slice. Otherwise,
stop and report.
3. Branch: follow the user's instruction; by default a dedicated branch when a
push to main triggers something. **Never push** — the user pushes.
4. First slice = the smallest and most self-contained one (a smoke test of the
pipeline: environment, conventions, sandbox).
5. `TaskCreate` one task per slice; `TaskUpdate` as you go.
6. Insert a prerequisite slice as soon as a cross-cutting blocker shows up
(e.g. test tooling missing for the new pattern) — never fold it into the
current slice.
## Loop per slice
1. Write the prompt (template below) — imposed interface, semantics to preserve
point by point.
2. Start Codex (mechanics below).
3. When it completes: its final message + `git diff --stat`. Targeted
inspection only on the risks announced in the prompt.
4. Run the gates **yourself** (never on the faith of a "green" announced by
Codex).
5. Commit (imperative message, repo conventions), complete the task, next slice.
## Codex prompt template
Always include, in this order:
- **Context**: stack + exemplary files to imitate ("follow the style of X"). Do
not ask it to read CLAUDE.md/AGENTS.md: Codex loads AGENTS.md natively (and
CLAUDE.md is often only an `@AGENTS.md` import).
- **Goal**: one sentence, with "zero behaviour change" for a refactor.
- **Imposed interface**: exact signatures (types, names, initial values), not an
intention.
- **Tricky points**: every semantic subtlety named explicitly, with the expected
behaviour and the suggested implementation.
- **Tests**: files, cases, naming conventions; "do not delete any existing test".
- **Forbidden**: git commit, new dependencies, files out of scope, + the repo's
own prohibitions.
- **Documentation**: wiki/comments per the repo's conventions, "keep it minimal".
- **Definition of done**: the exact gate command, "fix until green", "do not
run [slow suites] (I will)", "short final summary: files + non-trivial
choices".
## Invocation mechanics
One run per slice, in its own directory. The prompt is written to a file with
the Write tool, never inline in the shell. Use the paths the commands print
literally: shell variables do not survive between Bash calls.
```bash
# 1. Create the slice's run directory; it prints <dir>:
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.ts" new orchestrate
# 2. Write <dir>/prompt.md (Write tool — content = the slice's prompt)
# 3. Start it in write mode against the target repository:
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.ts" start <dir> --prompt-file <dir>/prompt.md --mode write --role coding -C /path/to/target-repo
```
- Run each `codex-run.ts` command alone, as written: a `;`, `&&` or `echo $?` added to it asks for permission, and the envelope's `status` already gives the exit code.
- **Pin the Codex version** for the whole orchestration: the first slice's
envelope carries `codex_version`; pass it to every later slice with
`--codex-version <x.y.z>`. Without it, the bridge may refresh its npm
resolution (24 h TTL) between two slices, and the version moves mid-run.
Corrections inside a slice resume the same run, which keeps its version.
- No `--git-write`: Codex never commits, so its sandbox keeps the git
directories read-only.
- A slice usually outlasts the call's 540 s wait: exit 10 means Codex is still
working. The turn runs detached; collect it with
`"${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.ts" wait <dir>`, repeated while it
exits 10, or start with `--wait 0` and do other work first.
- A non-git target needs `--skip-git-repo-check`.
- Corrections → write `<dir>/fix-2.md` and resume the thread (cheaper than a
fresh context); resume replays the model, effort, mode and cwd:
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.ts" resume <dir> --prompt-file <dir>/fix-2.md
```
## Failure protocol
- Red gate → diagnose first: **code failure** (resume the Codex thread with the
exact error report) or **environment failure** (files out of scope, config,
tooling — fix it yourself, it is the orchestrator's job, not the executor's).
- Exit 11 (blocked): Codex's auto-review or its sandbox refused an action, listed
in the envelope's `blocked`. Rule on each item as the `codex` skill's "Blocked
actions" section says; a slice that needs an action outside its sandbox is
often a slicing defect.
- Two failures on the same slice → stop, report to the user. Do not insist.
- Codex deviating from the spec → judge on the evidence: if the contract is
preserved and the design defensible, accept and note it; otherwise resume with
a correction.
## Known pitfalls (lived)
| Symptom | Cause | Fix |
|---|---|---|
| `npm E404` on the tarball, exit 1 with the npm error in `error` mid-orchestration | upstream `latest` dist-tag broken, re-resolved over the network | environment failure, not code: the bridge falls back to the last installed version on its own; `--codex-version` from the first slice avoids any re-resolution mid-run |
| Red gate on files never touched | outside pollution (installed skills, artefacts) | hygiene fix yourself (ignore files), not by Codex |
| Codex announces green, local gate red | different environments | always re-run the gates yourself |
| Slice N depends on missing tooling | cross-cutting prerequisite found late | insert a slice, never fold it in |
Versions
The database has no other skills named codex-orchestrate.
Database snapshot: 13.11.2026 · package version c356672911c0 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100orchestrate
Use when you need the Codex Copilot equivalent of Claude Copilot /orchestrate: plan stream-based work, validate dependencies, and coordinate explicit user-approved Codex subagent execution. - 100plan-orchestrate
Read a plan document, decompose it into steps, design a per-step agent chain from the ECC catalogue, and emit ready-to-paste /orchestrate custom prompts. Generative only — never invokes /orchestrate itself. Use when the user has a multi-step plan and wants to drive it through… - 90Codex Integration
Use this skill when delegating complex coding tasks to OpenAI Codex CLI and coordinating work between Claude and Codex. - 100orchestrate-agents
Coordinate project work across Codex, Claude Code and Google Antigravity. Use for model and effort routing, starting or resuming provider chats, coordinating implementers and independent reviewers, or tracking verified progress on large tasks. - 90codex-delegate
Orchestrate an implementation task where Claude plans and coordinates while OpenAI Codex performs the actual code edits; plans are cross-reviewed with Codex at its highest reasoning effort before implementation. Use when the user asks to "use codex", "use gpt", "use gpt-5.5",… - 90Codex Framework
Reference knowledge for OpenAI Codex CLI compatibility — how Codex discovers AGENTS.md instructions and .agents/skills so a Forge (Claude Code) project can interoperate with Codex without duplicating agent definitions. Use when a user asks to "add Codex support", make the repo…