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

## Language
All prompts passed to `codex` MUST be in English.

## Prompt Delivery
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`

## Context Classification

Before writing the prompt file, classify available context on two orthogonal axes:

- **AI-verifiable × Session (already available)** — extract paths, patterns, commands as **Pointers**; codex self-verifies them.
- **AI-verifiable × Exploration (needs collection)** — provide search hints and entry points; codex self-explores from them.
- **User-specific × Session (already available)** — summarize intent, constraints, and preferences from the current session, **copy-only**.
- **User-specific × Exploration (needs collection)** — **blocked**; this cell carries no collection requests or questions.

**Test each item before including it**: *"Can codex re-derive this from shared substrate with its own tools?"* — yes → pass a pointer; no → copy it in.

**Rules**:
- **Pointers**: Provide file paths, grep patterns, test commands. Reserve copying for what codex cannot re-derive.
- **Session Context**: Extract only what is already known from the current conversation. Organize as intent, constraints, and preferences.
- **No collection requests**: The prompt carries only user-specific information already in hand; when codex needs more, the user supplies it on resume. This bounds the prompt file only — pre-prompt orchestration stays free, so the `AskUserQuestion` permission gate in Error Handling is fine.

### Prompt Template

Structure `<scratchpad>/codex_prompt_<suffix>.txt` with these sections:

    ## Task
    [User's request — framed as a complete end-to-end objective]

    ## Pointers
    - files: [relevant file paths for codex to read/verify]
    - patterns: [grep patterns or keywords to explore]
    - commands: [test/build commands if relevant]

    ## Session Context
    - intent: [user's goal in one sentence]
    - constraints: [limitations, compatibility requirements]
    - preferences: [coding style, library choices, conventions]

Omit empty sections.

## Consult Mode (review, not execution)

A consult asks codex to judge a decision rather than carry out work — the reasoning is the deliverable, not a changed file. Four things differ from a task run.

**Declare the role.** Every prompt this skill sends names the role codex is acting in, taken from what the request actually asks for rather than from a fixed set; a consult names a **reviewing** role — codex is asked what it thinks of a decision, not to implement it. Make that call yourself and write it down rather than leaving it to be inferred from the prompt's shape.

**Carry the decision; point at everything else.** The part codex cannot re-derive with its own tools is the decision — what is being chosen, the approach taken so far and where it is still uncommitted, and the item most often omitted: **what would change the answer**, the evidence or outcome that would flip it. State those. Everything else goes through `## Context Classification`'s test: a pointer when codex can re-derive it under `-C DIR`, copied in when it cannot — in practice the session-bound evidence that left no trace on disk. Codex searches for itself, and handing it the tools beats transcribing what the search would have found. A consult invites follow-up, so pass the same `-C` again when you resume one: the pointers mean nothing without the tree they were written against.

**Take the reviewer's own words, not the summary.** The run goes through a Bash subagent, so its outcome summary is normally all that comes back — which for a consult discards the part that mattered. Pass `-o <FILE>` to write codex's final message verbatim, then read that file instead of relying on the summary. Give that path the same per-invocation uniqueness as the prompt file, plus the model name when consulting several in parallel — one shared path and the reviewers overwrite each other, leaving an answer that reads complete but is not the one you think.

**Leave the sandbox at its default, and no ask when the caller already decided.** Do not reach for `-s`: the default is `workspace-write` with network access, and a consult routinely needs the network to check a claim against a live source rather than against its own recollection. The default permits writes, so what keeps a consult from editing is the reviewing role declared above — not the sandbox. When the caller arrives with the model and reasoning effort already fixed, use those and skip the model/effort question in `## Running a Task` step 1.

## 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. Run on `gpt-6-astra` at `medium`. Whatever the caller named upstream — a model, an effort, a service tier, several models at once — overrides that default and IS the answer: pass it through and do not re-ask it.

   What an override 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. Craft prompt per Context Classification and Prompt Template — classify context, write 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 codex takes them from `~/.codex/config.toml`, so a consult comes back on whatever that file names; 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` (effort defaults to `medium`; `-r` raises it); 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 reference before writing a prompt for `gpt-6-astra`, and again whenever a
run came back having stopped early or asked a question instead of deciding.

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

Key sections (grep patterns for navigation):
- `## Model facts` - effort ladder, context window, knowledge cutoff, price, parameters to stop sending
- `## Autonomy and stop conditions` - astra asks non-blocking questions by default; what an unattended `codex exec` prompt has to state in place of that
- `## Instruction priority` - astra weighs in-context material more heavily, and conflicting guidance in a skill file stops work early
- `## Context discipline` - why this skill's pointer-over-copy rule matters more under astra rather than less
- `## Reconcile before switching` - what to send when astra's answer contradicts evidence already in hand
- `## Choosing an effort rung` - reading the rung off the task instead of off habit
- `## Subagents` - what a spawned agent inherits, and how to override it

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