Image Generation

Image Generation

Two jobs, in this order:

1. You write the spec. Turn the user's brief into a production prompt spec in the schema Codex's own imagegen skill expects. This is the point of the skill: a reasoning model sits in front of the image model. Never forward the brief verbatim.
2. Codex generates. One codex exec run calls Codex's built-in image_gen tool (gpt-image-2) and saves the file. No OPENAI_API_KEY required.

Benchmarked on 2026-09-02 across ten briefs: the spec beat the verbatim brief on seven and tied three, and raising Codex's reasoning effort did not change a single result. See the README.

Prerequisites

• Codex CLI installed, logged in, and new enough for the configured model. codex --version prints a version and codex login status reports a login. Every flag below exists on Codex 0.148 and later. Since Codex 0.153.4 the bundled default agent model is GPT-6 Astra (gpt-6-astra); a CLI older than 0.153 fails with The 'gpt-6-astra' model requires a newer version of Codex when that model is configured, so keep Codex current (npm install -g @openai/codex@latest, or your package manager). If Codex is missing or logged out, tell the user to install it and run codex login. If OpenAI's Codex plugin for Claude Code (codex@openai-codex) happens to be installed, /codex:setup can diagnose it, but this skill does not depend on that plugin.
• Codex's bundled imagegen system skill at ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md. It ships with Codex; if it is missing, the user should upgrade Codex.
• POSIX shell (bash/zsh). On Windows, run from WSL or Git Bash.

No other host assumptions: paths come from $HOME, $CODEX_HOME, $TMPDIR and Claude Code's cwd.

Costs

Per image: one gpt-image-2 generation plus roughly 20–25k Codex agent tokens and one to two and a half minutes at Codex's default reasoning effort. Writing the spec adds about fifteen seconds. Do not raise Codex's reasoning effort for this skill: xhigh costs about forty percent more time and buys nothing once the spec is written. For batches, prefer one run with a count over N runs. Codex validates what it generated and may re-render once or twice inside a single run when the aspect or the alpha comes out wrong; each re-render is another gpt-image-2 generation. Stating the canvas aspect in Constraints, not only in Asset type, reduces this.

When to use

Any raster request: "generate an image", "make a mockup", "draw me", "render a sprite", "a hero image for", "a logo for", "an infographic showing".

Skip when the user wants an SVG or vector icon (edit the SVG), an extension to an existing icon or logo set (edit the sources), or HTML/CSS/canvas graphics (write the code).

Inputs

• Brief (required). The user's words. They go into the spec's Primary request line unchanged.
• Output path or folder (optional). Resolve in this order: an explicit path the user named; otherwise ./tmp/imagegen/ at the git repo root if cwd is inside a repo; otherwise ~/Downloads/. If the user gave a full filename, use it. If they gave only a folder, or nothing, you choose a descriptive kebab-case filename such as hero-pickleball-golden-hour.png. Never let Codex pick the name.
• Aspect or size (optional). The built-in tool pins size to auto, so treat any size the user gives as an aspect hint in the spec (square, 16:9, 9:19.5 phone) and verify the real dimensions after the run. Exact pixel dimensions cannot be guaranteed on this path; if the user needs them, say so before running.
• Count (optional, default 1). For more than one, the spec describes each asset or variant and Codex is told to issue one image_gen call per asset.
• Reference images (optional). Pass each with --image <PATH> and label its role in the spec: reference, edit target, or style.

Ask a question (via AskUserQuestion) only when the subject is missing, or when the asset must carry factual copy the user did not supply: prices, dates, names, claims. For everything else, decide.

Step 0 — Write the spec

Use the imagegen skill's own schema. Include only the lines that change the output; skip the rest.

Use case: <one slug: photorealistic-natural | product-mockup | ui-mockup | infographic-diagram | scientific-educational | ads-marketing | productivity-visual | logo-brand | illustration-story | stylized-concept | historical-scene | text-localization | identity-preserve | precise-object-edit | lighting-weather | background-extraction | style-transfer | compositing | sketch-to-render>
Asset type: <where it will be used, aspect, and what sits on it later, e.g. "landing-page hero, 16:9, headline copy overlaid on the left third">
Primary request: <the user's brief, verbatim>
Input images: <Image 1: role; Image 2: role>            (only with references)
Subject: <the one thing the image is about, concretely>
Scene/backdrop: <environment or ground; "seamless white" or "fully transparent (true alpha)" when that is the point>
Style/medium: <photo / flat vector / hand-painted game art / 16-bit pixel art ..., with lens and film cues for photos>
Composition/framing: <camera position, placement, negative space, padding, frame count and layout for sheets>
Lighting/mood: <key light direction, time of day, mood>
Color palette: <named colors or hex values when they matter>
Materials/textures: <surface details>
Text (verbatim): "<every string that must appear, exact case, punctuation and line breaks>"   or   none
Constraints: <must-keep facts: counts, physical correctness, platform conventions, no logos, no watermark>
Avoid: <three to six clichés of this asset class>

Rules for the spec:

• Keep the user's intent intact. Do not change the subject, count, medium or style they named. Do not add characters, objects, brand names, slogans or palettes that are not implied by the brief. Add the production detail a generic brief lacks: intended use, aspect, composition, lighting, palette, constraints.
• Write out every text string. If the asset carries text, spell each string exactly, with case and line breaks, and say where it goes. If no text is wanted, say Text (verbatim): none and add "no text" to Constraints.
• Give each asset class what it needs.
  • Hero / marketing: where copy will be overlaid and keep that region soft and empty; one subject; no dashboards, HUD widgets or text unless asked.
  • Product photo: seamless white ground, three-quarter angle slightly above, softbox key light, soft contact shadow, one object, no props.
  • Logo: flat, vector-friendly, no gradients, two colors unless asked, exact wordmark text, must read at 32 px; avoid badge clutter, mountains, the generic cup-with-steam.
  • UI mockup: platform conventions (iOS status bar showing 9:41), exact labels, a state that adds up (three of five done means three checks), screen only unless a device frame is asked, no lorem ipsum.
  • Infographic / diagram: exact title, numbered stages with short captions, relationships written out so they come out physically or scientifically correct, color coding, labels never overlapping art.
  • Sprite / cutout: fully transparent background with true alpha, no ground shadow, even padding, upper-left key light, crisp silhouette. Sprite sheets: exact frame count, identical frame size, one shared baseline, no anti-aliasing for pixel art.
  • Photo / editorial: lens and aperture, natural light, a candid direction rather than a pose, realistic hands, no readable screens, no logos.
  • Ad / social: kicker, headline, detail line and call to action as separate exact strings, safe margins, one product.
• State the canvas in Constraints too. Size is auto, so the aspect is inferred from the prompt. Write it twice, in Asset type and in Constraints ("square canvas, 1:1"), or the model may pick portrait for a tall subject and Codex will spend a re-render fixing it.
• Length: 120 to 300 words. Every line must change the picture; cut anything that does not.
• Unfamiliar class? Read ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/references/sample-prompts.md for Codex's own recipes before writing.

Example, from the brief "product photo of a ceramic coffee mug for an online store":

Use case: product-mockup
Asset type: e-commerce main product image, square 1:1, on a white listing page
Primary request: product photo of a ceramic coffee mug for an online store
Subject: a single matte stoneware mug, warm off-white glaze, unglazed clay rim, handle facing right, three-quarter view from about 20 degrees above, empty so the glazed interior shows
Scene/backdrop: seamless pure white; the mug stands on the same white surface with a soft, short contact shadow and a faint reflection
Style/medium: photorealistic commercial product photography, 85mm look, everything in focus, neutral white balance
Composition/framing: mug centered, about 65% of frame height, equal margins, nothing else in frame
Lighting/mood: large softbox key from upper left, white fill from the right, gentle rim highlight, no hotspots
Text (verbatim): none
Constraints: square canvas, 1:1; physically correct handle; consistent glaze; no text, logos, props or liquid
Avoid: wood tables, plants, beans, steam, lifestyle scene, multiple mugs

Step 1 — prepare paths, result file and spec file

The result file needs a stable path that survives between Bash tool calls. Do not use $$: each Bash call is a fresh subprocess, so $$ changes between calls. Use mktemp, capture the printed path, and reuse that literal path later.

Save the spec beside the image as <OUTPUT_PATH minus extension>.spec.md. It documents what was sent and makes the next revision a diff rather than a rewrite. Writing it with a heredoc is fine here; the heredoc feeds a file, not Codex.

mkdir -p "<OUTPUT_PARENT>"
RESULT_FILE="$(mktemp -t imagegen-result.XXXXXX)"
cat > "<SPEC_FILE>" <<'SPEC'
<the spec from Step 0>
SPEC
echo "$RESULT_FILE"

<OUTPUT_PARENT> is dirname "<OUTPUT_PATH>". Capture the printed RESULT_FILE path; it is the literal value used in Step 2 and Step 3.

Step 2 — run Codex

One Bash call. Set the Bash timeout to ten minutes (600000 ms, the tool's maximum) or use run_in_background: true; a run usually takes one to three minutes but a single image can take five or more when Codex inspects and verifies its output.

PROMPT="Use \$imagegen to generate <COUNT> image(s) with the built-in image_gen tool. Use the following prompt spec as the image_gen prompt. You may normalize its formatting, but do not add or remove creative requirements:

$(cat "<SPEC_FILE>")

Rules: built-in image_gen only (it uses gpt-image-2). Do not use the CLI fallback (scripts/image_gen.py) and do not switch to gpt-image-1.5; do not propose or ask about either. For a transparent background, ask image_gen for a transparent background and preserve its alpha. For more than one asset, issue one image_gen call per asset. Save the final image(s) to <OUTPUT_PATH> (copy from \$CODEX_HOME/generated_images). Report each saved absolute path on its own line prefixed exactly with 'SAVED: '. Do not modify any other files."

codex exec --sandbox workspace-write --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>" \
  "$PROMPT" \
  </dev/null

Substitute <COUNT>, <SPEC_FILE>, <OUTPUT_PATH>, <OUTPUT_PARENT>, <CWD>, <RESULT_FILE> and optionally <REFERENCE_IMAGE_PATH>. The spec arrives through $(cat ...), so nothing inside it needs shell escaping; keep the \$ escapes in the fixed text so Codex sees $imagegen and $CODEX_HOME literally.

</dev/null is mandatory. With a piped, still-open stdin, codex exec prints Reading additional input from stdin... and waits forever. Never pipe the prompt through stdin.

Why each flag:

• --sandbox workspace-write — file writes allowed inside the workspace and the --add-dir roots; the sandbox stays on. codex exec never prompts for approval, so nothing else is needed. (--full-auto was removed from codex exec in Codex 0.147; do not use it.)
• --add-dir "<OUTPUT_PARENT>" — makes the destination writable so the final copy succeeds.
• --add-dir ".../generated_images" — makes Codex's own image cache writable so it can stage and move the file.
• --skip-git-repo-check — works from any directory.
• --cd "<CWD>" — pins Codex's working root to Claude Code's cwd so relative paths resolve as the user expects.
• --image — attaches a reference image to the prompt. Repeatable.
• --output-last-message — captures Codex's final message without parsing terminal noise.

Do not pass -m, -c model_reasoning_effort=... or any other config override; the user's Codex configuration applies. If the user explicitly asks for an unsandboxed run, --dangerously-bypass-approvals-and-sandbox replaces --sandbox and both --add-dir flags; never default to it.

Step 3 — output handling

1. Read the literal <RESULT_FILE> path from Step 1.
2. Collect every line starting with SAVED: .
3. For each path, confirm it exists and note its dimensions: ls -lh <path> plus sips -g pixelWidth -g pixelHeight <path> on macOS or file <path> elsewhere. For a transparent request, also confirm alpha (sips -g hasAlpha on macOS).
4. If <COUNT> was greater than one, the number of SAVED: lines must equal <COUNT>; otherwise surface the discrepancy and stop.
5. Reply with exactly:

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

   Nothing more: no commentary, no description of the image, no offer of changes. The spec file stays beside the image but is not listed.
6. rm -f "<RESULT_FILE>".

If the Bash call exited non-zero, or the last message has no SAVED: line, or a transparent request came back without alpha, or the file is missing:

• Quote Codex's last message verbatim.
• If it indicates Codex is missing or logged out, tell the user to install Codex or run codex login.
• If it says the configured model requires a newer version of Codex, tell the user to upgrade Codex. Do not work around it with -m; a different agent model changes the results this skill was benchmarked on.
• Stop. Do not retry, do not call the OpenAI API directly, do not generate a placeholder. Still remove the result file.

Hard rules

• Write the spec first, always. The brief goes into the spec verbatim; the spec is what Codex receives. Never send the brief alone.
• Never invent facts. Prices, dates, names, claims and other factual copy come from the user or from one clarifying question, not from you.
• gpt-image-2 via the built-in image_gen tool only. No scripts/image_gen.py fallback, no gpt-image-1.5, not for transparency, not on request from Codex. If Codex offers either, decline and stop.
• Transparency is native. Ask image_gen for a transparent background and preserve its alpha. Do not use chroma-key backdrops or remove_chroma_key.py.
• --sandbox workspace-write, never --full-auto. Always close stdin with </dev/null. Never pipe the prompt through stdin.
• Use mktemp, never $$, for the result-file path.
• Do not touch Codex's reasoning effort or model. The user's Codex config applies.
• One Codex run per user request; no automatic iteration.
• Never call the OpenAI Images API directly. Never modify files under ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/.
• On failure, return Codex's output verbatim; never paraphrase it.