git:20260923.650f333 to git:20260926.95b2a39

---

name: codex-plus

description: |

This skill should be used when the user asks to "run codex", "use codex CLI", "delegate to codex", "codex resume", or "continue with codex". Executes tasks via OpenAI Codex CLI with model selection, reasoning effort configuration, and session management.

---

# Codex Skill Guide

## Prompt Delivery

Read `references/run-brief.md` before writing the prompt file: the role every prompt declares, what a prompt judging a decision carries, and how the model is chosen.

1. Generate a short unique suffix (e.g., `a3f9`, timestamp fragment, or task keyword) for this invocation

2. Write the prompt to `<scratchpad>/codex_prompt_<suffix>.txt` using the Write tool — `<scratchpad>` is the session's scratchpad directory, the `/private/tmp/…/scratchpad` path announced in the system prompt; writes there run without permission prompts. When no scratchpad directory is announced, fall back to `/private/tmp`.

3. Execute via wrapper script: `${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.sh [options] <scratchpad>/codex_prompt_<suffix>.txt`

## Image Generation Requests

When the delegated task is image generation or image editing:

- Include `$imagegen` in the prompt so downstream clients treat it as an explicit image-generation request.

- Keep the local prompt here minimal and task-specific.

- Defer prompt construction details to the installed `imagegen` skill when available. Codex's bundled copy predates GPT-Image-2.5: it names `gpt-image-2` as the CLI/API default and routes a transparent background to `gpt-image-1.5`. Name `gpt-image-2.5-flare` instead — GPT-Image-2 quality or better at roughly half the latency — and `gpt-image-2.5-sunburst` where the cost of the task is a retry on an edit: multi-turn editing, identity or layout that has to survive several passes, campaign and product work where the precision is what is being paid for. 2.5 renders alpha natively from `background: "transparent"` with `output_format` `png` or `webp`, and its quality ladder runs `low|medium|high|xhigh|max|auto`.

- Read OpenAI's GPT Image 2.5 prompting guide — https://developers.openai.com/api/docs/guides/image-prompting — for model parameters, per-use-case prompt structure, text rendering, edits, multi-image workflows, and migrating a workflow off an earlier model. It carries reference sections for GPT Image 2, 1.5 and 1 as well.

## Running a Task

1. Choose the model and effort. Whatever the caller named upstream — a model, an effort, a service tier, several models at once — IS the answer: pass it through and do not re-ask it. Otherwise choose per request, as `references/run-brief.md` § Choosing the model and effort says.

What a choice may name:

- **Model** — any slug `codex debug models` lists.

- **Effort** — `low`, `medium`, `high`, `xhigh`, `max`. A model's ladder may stop short of `max`, and a parallel run needs an effort every model in it takes; `codex debug models` reports each model's ladder.

- **Service tier** — `-f`, under the caveat in the Quick Reference.

2. Select sandbox mode. Omitting `-s` gives `workspace-write` **with network access** — codex offers no network under `read-only` at all, so this is the only mode short of full access that has any. Pass `-s read-only` when a run must neither touch the tree nor reach off-machine; `-s danger-full-access` only when it must write outside the workspace. Because the default already permits writes, what bounds a run that is meant to only read is the role its prompt declares — state it.

3. Write the prompt per `references/run-brief.md` to `<scratchpad>/codex_prompt_<suffix>.txt`.

4. Delegate execution to a Bash subagent (Task tool) — never run `codex-run.sh` directly in the main session. This keeps codex's verbose banner and full output out of the main context. Give the subagent:

- the exact command: `${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.sh [options] <scratchpad>/codex_prompt_<suffix>.txt` with `-m MODEL` / `-r EFFORT` / `-s SANDBOX` / `-C DIR`, or `-S <SESSION_ID>` to resume.

- return contract: run the command and return ONLY (a) a concise outcome summary and (b) the session id. codex prints `session id: <uuid>` to stderr; the subagent extracts that line verbatim and returns it as `SESSION_ID: <uuid>`. The wrapper does no parsing — stderr is left unsuppressed precisely so the subagent can read the session id and any failure straight from the output.

- **Single model**: one subagent call.

- **Multiple models**: issue parallel subagent calls (one per model) in a single response — same prompt, sandbox, and effort, different `-m`. Each returns its own `SESSION_ID`.

5. Record each returned `SESSION_ID` against its purpose/model. This {purpose → SESSION_ID} map is the only resume handle.

6. Resume: write new instructions to a fresh `<scratchpad>/codex_prompt_<suffix>.txt`, then delegate to a Bash subagent running `${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.sh -S <SESSION_ID> <scratchpad>/codex_prompt_<suffix>.txt`. Resume is always by explicit id, which stays deterministic under parallel sessions. **A resumed turn inherits none of the session's settings except its sandbox** — pass `-m`, `-r`, `-C` and `-f` again to stay where the session was. Omit `-m`/`-r` and the wrapper passes its own fallback, `gpt-6-astra` at `medium`, so a resumed run started on another model silently moves to astra; omit `-C` and the turn runs wherever the subagent happens to be, re-resolving every pointer against that tree. Only `-s` is fixed at session creation and cannot be set on resume at all.

7. Summarize each outcome to the user; for parallel work, surface which `SESSION_ID` maps to which branch. Inform the user: "Resume anytime with 'codex resume'."

### Quick Reference

Each command below runs **inside a Bash subagent**, which returns the outcome summary plus the `session id: <uuid>` line as `SESSION_ID: <uuid>`.

Base patterns:

- Analysis or unattended edits, network reachable — `${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.sh -m MODEL <scratchpad>/codex_prompt_<suffix>.txt` (the default sandbox: workspace-write, network on — it applies edits without prompting, because `codex exec` is headless and has no approval step to opt out of)

- Neither writes nor network — `${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.sh -s read-only <scratchpad>/codex_prompt_<suffix>.txt`

- Write outside the workspace — `${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.sh -s danger-full-access <scratchpad>/codex_prompt_<suffix>.txt`

- Resume a session — `${CLAUDE_PLUGIN_ROOT}/scripts/codex-run.sh -S <SESSION_ID> -m <SAME_MODEL> -r <SAME_EFFORT> <scratchpad>/codex_prompt_<suffix>.txt`; the explicit id is the resume path, deterministic under parallel sessions.

Modifiers, added to any base pattern above:

- Different working directory — `-C <DIR>`; pass it again on resume (step 6)

- Model and effort — `-m MODEL`, `-r EFFORT` (omitted, the wrapper falls back to `gpt-6-astra` at `medium`); pass both again on resume (step 6)

- Fast service tier — `-f`; a request rather than a guarantee, since codex drops the tier without an error where the model does not carry it (`codex debug models` lists what each one has). Pass it again on resume (step 6)

- Capture the answer to a file — `-o <FILE>` writes codex's final message to FILE deterministically

## Error Handling

- Stop and report failures whenever `codex --version` or a `codex exec` command exits non-zero; request direction before retrying.

- Before you select `-s danger-full-access`, ask the user for permission using AskUserQuestion unless it was already given. `--skip-git-repo-check` is not a choice you make: the wrapper passes it on every run, because a prompt file in a scratchpad is routinely outside any repository.

- When output includes warnings or partial results, report them beside the outcome summary.

## Reference Guide

Read the prompting guide before writing a prompt for a gpt-6 model, and again whenever a

run came back having stopped early or asked a question instead of deciding.

**File**: `references/gpt-6_prompting_guide.md`

That file keeps only what changes for an unattended `codex exec` run. For the rest of

prompting the gpt-6 family — its best practices and migration notes — read OpenAI's

guide itself: https://developers.openai.com/api/docs/guides/latest-model

- Before delegating browser or native computer-use work, read

`references/computer-use.md` and pass it to the child prompt. Select the entry

point from that child's actual tools and returned runtime documentation.

- After a local UI run fails, match the observed failure against

`references/computer-use-troubleshooting.md`.