Codex Image Generation

Delegate raster image generation and editing to Codex's built-in $imagegen capability, then return a verified workspace artifact to the leader harness.

Core insight: instrument Codex, not the desktop window. When the configured codex exec environment exposes image generation, use it headlessly and hand off the resulting artifact through the shared filesystem. Authentication alone does not establish tool availability.

As of Jul 2026, this path is verified with codex-cli 0.144.6. CLI and tool availability are volatile; the installed CLI and a live invocation outrank this snapshot.

Select the Execution Route

Run codex --version before the first delegated call. Respect the user's Codex configuration; never set --model, -m, or -c model=. Authentication, entitlements, workspace policy, and image-generation availability belong to the installed Codex environment.

Use the user's normal Codex session configuration. This skill bundles no Codex agent profile and requires no model or reasoning override.

Do not start or automate the ChatGPT desktop app. Do not install an MCP server, change Claude configuration, or switch to API billing unless the user asks.

Establish the Artifact Contract

Resolve these inputs before launching Codex:

Resolve relative paths against the leader's current workspace. For a project asset with no user-specified destination, keep the final asset inside that workspace. Honor explicit destinations outside it when authorized. Keep the child's output in the workspace, then have the parent copy that exact verified artifact to the authorized external destination and verify the copy. A workspace-write child is not assumed to have external write access. Built-in generation may initially save under $CODEX_HOME; that location is staging, not a valid final destination for a project asset.

Delegate with codex exec

Use a single-quoted heredoc so prompts containing backticks, $(), quotes, or shell metacharacters remain data. Before executing, confirm IMAGEGEN_BRIEF does not appear as an exact standalone line in inserted content; if it does, choose a different quoted delimiter and update both marker lines. Omit -i when there are no input images.

codex exec \
  --ephemeral \
  --sandbox workspace-write \
  -C "$PWD" \
  -i "/absolute/path/to/reference.png" \
  - <<'IMAGEGEN_BRIEF'
$imagegen

Create or edit the requested raster asset.

Intent: <generation | edit | refinement | variant>
Asset purpose: <where and how the image will be used>
Primary request: <the user's request, preserving their specificity>
Input images:
- Image 1: <edit target | content reference | style reference | compositing input>
Destination: <workspace staging path, or final path when inside the workspace>
Text (verbatim): "<exact text, or none>"
Must preserve: <edit invariants, or none>
Constraints: <required properties>
Avoid: <negative constraints>

Execution requirements:
- Use the built-in image-generation tool. Do not substitute SVG, HTML, CSS,
  canvas, stock imagery, or a hand-authored placeholder.
- Do not switch to an Images API script, another model path, or paid API
  fallback.
- Inspect the generated result visually. Check subject, composition, text,
  constraints, and edit invariants.
- If one focused correction is clearly necessary, make that correction and
  inspect again. Do not wander through speculative variants.
- Move or copy the selected final into Destination. Do not leave the only copy
  in a temporary generation directory.
- Do not overwrite an existing destination unless the brief explicitly allows
  replacement.

Return this receipt:
STATUS: complete | blocked
MODE: built-in-imagegen
FILES:
- <absolute final path>
FINAL PROMPT: <the prompt actually used>
VERIFICATION:
- <what was visually checked>
NOTES: <material limitations, or none>
IMAGEGEN_BRIEF

codex exec refuses to launch when -C targets a directory outside a trusted git repository, failing with Not inside a trusted directory and --skip-git-repo-check was not specified. Add --skip-git-repo-check only when the workspace is deliberately not a git repo, such as a scratchpad or temporary build area. Inside a project repo, omit the flag and keep the trust check.

For multiple input images, add one -i argument per file and preserve the same ordering in the brief. Use absolute paths when the leader and Codex might resolve working directories differently.

Do not launch a duplicate while codex exec is alive. Image generation may outlast a harness's first yield window; poll the existing process or session. Treat output growth and process state as liveness signals, not elapsed time.

Handle Each Image Shape

Do not use one broad batch prompt for unrelated assets. Distinct assets need distinct prompts; otherwise one failure makes the receipt ambiguous and visual constraints bleed between outputs.

Parallel multi-image generation

Inspect the current tool's batch and reference-image semantics. When assets are independent and the host permits delegation, fan out jobs with separate prompts and receipts. A tool's supported batch output may also be appropriate; verify each requested asset individually.

Before launch, assign every job a deterministic destination such as concept-01.png, concept-02.png, and concept-03.png. Give each process its own prompt and receipt. Shared reference images may be read by every job; output paths and temporary receipt paths must never collide.

Use the leader's native parallel tool dispatch when available. Do not hardcode an arbitrary concurrency cap into the skill; honor the harness and account capacity already in force. If the host cannot dispatch concurrently, preserve the same isolated job shape and run it sequentially.

Track completion as N/total. On partial failure, keep and report successful assets, then retry only failed jobs after diagnosing their exact errors. Never discard a valid sibling or rerun the whole batch to make the reporting look atomic.

For an edit, use language such as:

Change only the background to a misty violet dawn. Preserve the subject,
silhouette, camera angle, crop, facial identity, clothing, and all foreground
edges. Add no text or watermark.

For a refinement, change one dimension at a time. "Keep everything else unchanged" is the part that does the work, not decoration.

Verify the Handoff

Codex's receipt is a claim until the leader verifies the filesystem artifact.

1. Confirm every reported final path exists at the agreed destination, resolving symlinks when checking workspace containment.
2. Confirm each file is non-empty and file <path> identifies the requested raster format.
3. Confirm no requested deliverable exists only in a temporary generation directory.
4. Inspect the asset in the leader harness when it has image-viewing support. Otherwise report that visual verification was performed by delegated Codex, not by the leader.
5. Present the image through the host's native image-return mechanism when available, and link the project artifact. Keep the full prompt and technical receipt for the parent harness; show details to the user when requested or needed to explain a limitation.

codex exec may echo the final receipt twice in one output stream, once as streamed agent output and once as the final message. Duplicate receipt text is one run, not two; count generations by process invocations.

If Codex generated successfully but failed to move the selected image, use the exact staging path from its receipt and copy it non-destructively into the workspace. Never hunt broadly through another user's generated-image history or guess which file belongs to the run.

If the final path is missing, the format is wrong, or the receipt is malformed, the task is not complete. Ask the same Codex session for a corrected handoff, or run one fresh, tightly-scoped call with the failed receipt and exact gap.

Optional Threaded MCP Route

Use MCP only when the Codex server is already configured or the user explicitly asks to configure it. A one-time Claude Code setup is:

claude mcp add --scope user codex -- codex mcp-server

The server exposes codex to start a session and codex-reply to continue it. Start with the same brief used for codex exec, set cwd to the shared workspace, and use sandbox: workspace-write. Preserve the returned threadId. Send targeted refinements through codex-reply, then verify the resulting files at the consumption boundary.

MCP improves conversational refinement; it is not more capable than the direct path. Do not make MCP configuration a prerequisite for one-shot generation.

Failure and Fallback Policy

Never silently downgrade to a different image model or API path. A fallback that changes billing, authentication, transparency behavior, or output semantics is a new user decision.

Anti-Patterns

Current Tool Contract

Checked on 2026-09-04 against OpenAI image-generation documentation and Codex non-interactive guidance. API capabilities do not prove that a particular Codex session exposes the same image tool. Follow the actual tool schema for references, output formats, and return mechanisms. CLI availability was not exercised in this audit environment; preserve that distinction from the historical snapshot above.

For edits, inspect the target before dispatch and identify every reference image's role. Verify requested dimensions and transparency from the output itself, not its extension or the prompt. A visible checkerboard is not an alpha channel. Inspect exact text at delivery size. Keep successful batch siblings and correct only the failed constraint.

What This Skill is NOT

• Not a generic image-prompt cookbook; Codex's native $imagegen skill owns detailed prompting and image-tool behavior.
• Not a vector, SVG, icon-system, HTML, CSS, canvas, or deterministic diagram workflow.
• Not desktop GUI automation.
• Not permission to incur API charges or change authentication.
• Not a replacement for human art direction or final production review when typography, likeness, legal clearance, or brand fidelity is critical.