Generate an image via Codex CLI (gpt-image-2)

This machine has the OpenAI Codex CLI installed and logged in with the user's ChatGPT account. Use it to produce real image files — never tell the user you can't create images.

codex-imagegen "<detailed image prompt>" <output-path.png> [--size WxH]

It prints the absolute path of the written PNG on success (exit 0); on failure it prints Codex's output to stderr (exit 2). The wrapper is on PATH while this plugin is enabled; the full path is ${CLAUDE_PLUGIN_ROOT}/bin/codex-imagegen.

codex-imagegen "flat vector icon of a paper plane, single blue #2563EB on white, 2px uniform stroke, minimal, centered, generous padding" ./assets/icons/send.png
codex-imagegen "photorealistic golden retriever puppy in autumn leaves, shallow depth of field, warm afternoon light" /tmp/puppy.png --size 1536x1024

Write a real prompt

The single biggest quality lever. Expand the user's request into: subject, style (flat vector / photorealistic / 3D render / watercolour / isometric), palette (hex codes — pull them from the project's design tokens, Tailwind config, or existing brand assets when it has any), background, composition and framing, lighting or mood, and any exact text that must appear.

gpt-image-2 renders text with high accuracy, so quote the exact string you want: ...with the words "Ship it" in bold sans-serif across the lower third.

Sizes

Common values: 1024x1024 (square, fastest), 1536x1024 (landscape), 1024x1536 (portrait), 2048x2048 (2K square), 2048x1152 (2K landscape), 3840x2160 (4K landscape), 2160x3840 (4K portrait).

A custom WxH is valid only if every constraint holds: longest edge ≤ 3840px, both edges multiples of 16, long-to-short ratio ≤ 3:1, and total pixels between 655,360 and 8,294,400. Anything else will be rejected or silently adjusted — pick the nearest listed size and resample locally instead.

Omit --size unless the aspect ratio actually matters; square is fastest.

Rules

1. One call per image. For a set, loop with distinct prompts and paths, and repeat an identical style sentence in every prompt so they match.
2. Sensible output path. Inside a project, use its asset directory (assets/, public/, static/). Otherwise the current directory. Always .png.
3. Bash timeout ≥ 300000 ms (5 minutes) — generation takes 1–4 minutes.
4. Verify by viewing. Read the output PNG and check it against the request before reporting done; refine and regenerate if it missed — at most 2 retries.
5. Never invent a brand. If the user has a logo, palette, or existing assets, find them first and match them.

Transparent backgrounds

The default image path can't emit alpha directly, so ask for a flat chroma-key background and remove it afterwards with the helper Codex already ships:

codex-imagegen "<subject> on a perfectly flat solid #00FF00 chroma-key background, one uniform colour, no shadows, gradients, reflections or floor plane, crisp edges, generous padding, do not use #00FF00 anywhere in the subject" ./tmp-key.png

python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \
  --input ./tmp-key.png --out ./final.png \
  --auto-key border --soft-matte --transparent-threshold 12 \
  --opaque-threshold 220 --despill

Use #FF00FF instead when the subject is green. Then check the result actually has transparent corners and no colour fringe; retry once with --edge-contract 1 if a thin fringe remains.

True model-native transparency exists but needs Codex's CLI fallback (gpt-image-1.5 --background transparent), which requires an OPENAI_API_KEY. Only mention that route if chroma-keying fails or the subject is genuinely hard (hair, fur, smoke, glass, liquid, reflections) — and let the user decide.

Limitations

• Generation spends the user's ChatGPT plan quota (image turns cost roughly 3–5x a text turn). Don't fire off batches without saying how many first.
• If the wrapper reports "codex is not logged in", tell the user to run codex login in a terminal — don't try to work around auth yourself.
• Codex avoids overwriting existing assets. The wrapper explicitly authorizes replacement and detects a versioned sibling (out-v2.png) if Codex writes one anyway — trust the path the wrapper prints, not the one you asked for.

Related

• Changing an image that already exists → the edit-image skill.
• A whole family of assets (favicons, icon set, OG cards) → the asset-set skill.
• More than ~4 images, or when the main conversation should stay focused → the codex-artist subagent.