Image generation

Image Generation

This skill is a thin wrapper around Codex's built-in imagegen skill. Claude Code parses the user's request, builds one Codex prompt, and shells out to codex exec --full-auto. Codex does the actual image generation via its built-in image_gen tool. No OPENAI_API_KEY required.

Prerequisites

The skill assumes the host machine has:

• Codex CLI installed and authenticated. codex --version should print a version, and codex login must have been completed at least once. If missing, point the user at /codex:setup.
• Codex's bundled imagegen system skill present. Lives at ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md. It ships with recent Codex CLI releases — no separate install. If it's missing, the user is on an older Codex; tell them to upgrade.
• POSIX shell (bash/zsh) for the </dev/null and mktemp syntax in the invocation. macOS and Linux work out of the box. On Windows, run from WSL or Git Bash.

The skill makes no other assumptions about the host — no hardcoded usernames, no project-specific paths. All paths use $HOME, $CODEX_HOME, $TMPDIR, or values resolved at runtime from Claude Code's cwd.

Costs

Each image is generated by codex exec spawning a Codex agent that calls image_gen internally. You pay for both:

• The image generation itself (gpt-image-2, billed per image).
• The Codex agent tokens used to drive the call. Expect ~30k agent tokens per single low-quality image, more for larger sizes or multi-image runs. These count against your Codex usage limit.

For batch work, prefer one Codex run with a <COUNT> instruction over N separate runs — the per-run agent overhead dominates the cost.

When to use

Activate when the user asks for a raster image: "generate an image", "create a picture", "make a mockup", "draw me", "render a sprite", "produce a hero image", "give me a 1024x1024 illustration of...", etc.

Skip when the user wants:

• An SVG or vector icon → edit the SVG directly.
• An extension to an existing icon/logo set → edit the source files.
• HTML/CSS/canvas-drawn graphics → write the code.

Inputs

Parse from the user's natural-language request (or explicit flags):

• Prompt (required) — the image description, verbatim from the user.
• Output path or folder (optional). Resolve in this order:
  1. Explicit path the user named ("save to ~/Desktop/foo.png", --out <path>).
  2. Otherwise, if Claude Code's cwd is inside a git repo: default to ./tmp/imagegen/ in the repo root.
  3. Otherwise: default to ~/Downloads/.
  • If the user gave a full path with extension, use it as-is. If they gave only a folder, let Codex auto-name and report the path back.
• Size (optional). Default 1024x1024. Pass any user-specified size through verbatim — gpt-image-2 validates allowed sizes (max edge ≤3840px, both edges multiples of 16, ratio ≤3:1, total pixels 655,360–8,294,400).
• Count (optional). Default 1. For >1, instruct Codex to issue one image_gen call per asset (do not use n as a substitute — Codex's imagegen skill explicitly requires separate calls for distinct assets). Verify the captured last-message file contains one SAVED: line per requested asset; if it does not, surface the discrepancy and stop.
• Reference image (optional). If the user attaches or names an existing image to influence style/composition, pass it as --image <PATH>. Repeatable for multiple references. Codex's image_gen enforces input-image limits; do not preprocess.

Only ask a clarifying question (via AskUserQuestion) if the prompt itself is missing or empty. Apply defaults silently for size / count / path.

Invocation

The temp file used to capture Codex's last message must have a stable, deterministic path that survives between separate Bash tool calls. Do not use $$ — it is the PID of the bash subprocess Claude Code spawns, and Claude Code spawns a fresh subprocess for every Bash tool call, so $$ resolves to a different value when you later try to Read the file. Compute the path once with mktemp, capture its name, and pass that exact literal path to both the codex exec invocation and the subsequent Read.

Step 1 — allocate the result file

RESULT_FILE="$(mktemp -t imagegen-result.XXXXXX)"
echo "$RESULT_FILE"

Capture the printed path. That is the literal value you will substitute for <RESULT_FILE> below and the literal path you will pass to Read after the run.

Step 2 — run Codex

One Bash call, foreground:

codex exec --full-auto --skip-git-repo-check --cd "<CWD>" \
  --add-dir "<OUTPUT_PARENT>" \
  --add-dir "${CODEX_HOME:-$HOME/.codex}/generated_images" \
  [--image "<REFERENCE_IMAGE_PATH>"] \
  --output-last-message "<RESULT_FILE>" \
  "Use the imagegen skill to generate <COUNT> image(s). Prompt (verbatim): <USER_PROMPT>. Constraints: Model: gpt-image-2 ONLY. Do not use gpt-image-1.5 under any circumstance. Do not use the CLI fallback (scripts/image_gen.py). Do not propose, suggest, or ask about either. Size: <SIZE>. Save the final image(s) to: <OUTPUT_PATH>. Use Codex's built-in image_gen tool exclusively. It uses gpt-image-2. For transparent-background requests: stay on built-in image_gen with the chroma-key workflow (flat #00ff00 backdrop, then \$CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py). If the chroma-key result is not clean enough, STOP and report that — do not switch models. After generation, move/copy the selected output(s) from \$CODEX_HOME/generated_images/... to the destination above. Report each final saved absolute path on its own line, prefixed exactly with 'SAVED: '. Do not modify any other files." \
  </dev/null

Substitute <CWD>, <COUNT>, <USER_PROMPT>, <SIZE>, <OUTPUT_PATH>, <OUTPUT_PARENT>, <RESULT_FILE> (and optionally <REFERENCE_IMAGE_PATH>) before invoking. Quote <USER_PROMPT> so it survives shell expansion intact.

Compute <OUTPUT_PARENT> as the directory containing <OUTPUT_PATH> — dirname "<OUTPUT_PATH>". If <OUTPUT_PATH> is itself a directory (no filename), use it directly. The skill must mkdir -p "<OUTPUT_PARENT>" before invoking Codex so the path exists when --add-dir resolves it.

</dev/null is mandatory. Without it, codex exec detects a non-tty stdin and hangs forever on Reading additional input from stdin..., never returning. Always close stdin.

Do NOT pass the prompt via heredoc / cat <<'PROMPT' command substitution. It triggers the same stdin-hang. Build the prompt as a single double-quoted string argument; escape any literal $ or backticks inside it.

Why each flag:

• --full-auto — convenience alias for low-friction sandboxed automatic execution. Codex runs in workspace-write sandbox with no approval prompts, so the move from $CODEX_HOME/generated_images/ to the destination happens without blocking. Sandbox stays on, unlike --yolo.
• --add-dir "<OUTPUT_PARENT>" — extends the writable sandbox to the destination directory so the final move/copy of the image succeeds. Without this, anything outside the workspace + cwd would be blocked.
• --add-dir "${CODEX_HOME:-$HOME/.codex}/generated_images" — extends the writable sandbox to Codex's own image-cache directory so the imagegen skill can stage the file before moving it. (Some Codex builds need this explicit even though it's Codex's own home.)
• --skip-git-repo-check — the skill must work from any directory, including non-repo cwds.
• --cd "<CWD>" — pin Codex's working root to Claude Code's current cwd so relative <OUTPUT_PATH> resolves the way the user expects.
• --image "<REFERENCE_IMAGE_PATH>" — optional; attach a reference image (face/style/composition) when the user provides one or when the skill resolved one from the project. Repeatable.
• --output-last-message <RESULT_FILE> — capture Codex's final assistant message cleanly. Avoids parsing TUI noise from stdout.

If you ever need to bypass the sandbox entirely (e.g. the user explicitly asks for an unrestricted run), swap --full-auto + --add-dir for --yolo (alias for --dangerously-bypass-approvals-and-sandbox). Default to --full-auto; it is the safer choice and works for every normal request.

The prompt goes as a single argument, not piped through stdin. Run in foreground or with run_in_background: true (gpt-image-2 typically takes 1–3 minutes per image; budget at least 5 minutes).

Output handling

After the Bash call returns:

1. Read the literal <RESULT_FILE> path captured from mktemp in Step 1.
2. Extract every line starting with SAVED: and collect the paths.
3. For each path, confirm it exists (ls -lh <path> via Bash).
4. If <COUNT> was greater than 1, verify the number of SAVED: lines equals <COUNT>. If not, surface the discrepancy and stop — do not silently report fewer.
5. Reply to the user with exactly:

   Generated <N> image(s):
   <abs-path-1>
   <abs-path-2>
   ...
   

   Nothing more. No commentary, no descriptions of the image, no "let me know if you'd like changes".
6. Clean up: rm -f "<RESULT_FILE>".

If the Bash call had a non-zero exit, or the captured last-message file has no SAVED: lines, treat it as a failure:

• Surface Codex's last message verbatim.
• If the message indicates Codex is missing or unauthenticated, point the user at /codex:setup.
• Stop. Do not retry. Do not attempt to call the OpenAI API directly. Do not generate a placeholder.
• Still clean up the temp file.

Hard rules

• gpt-image-2 only. This skill never uses gpt-image-1.5. Not as a fallback, not for transparency, not on user request, not ever. If Codex offers a fallback to gpt-image-1.5, decline and stop.
• No CLI fallback. Do not use scripts/image_gen.py. Do not pass any flag, prompt, or instruction that selects the CLI path. The built-in image_gen tool (gpt-image-2) is the only allowed engine.
• Transparency stays on the chroma-key path. Use built-in image_gen with a flat chroma-key backdrop, then $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py. If the result has fringe/halo issues, retry once with --edge-contract 1. If still bad, STOP and report — do not propose gpt-image-1.5.
• Always close stdin (</dev/null) on the codex exec call. Without it, Codex hangs on Reading additional input from stdin... indefinitely. Never use heredoc command substitution to build the prompt — same hang.
• Use mktemp, never $$, for the result-file path. Bash tool calls do not share a subprocess; $$ will not resolve to the same value across calls.
• One Codex run per user request. No automatic iteration or revisions.
• Never call the OpenAI Images API directly from Claude Code. The whole point of this skill is to delegate to Codex.
• Never invoke node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" — its task / review subcommands have no imagegen route. Always use codex exec directly.
• Never modify files under ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/.
• Never paraphrase Codex's output on failure — return it verbatim, like the existing codex:codex-rescue and codex:codex-result-handling skills require.