Generate Image

---
description: Generate images (icons, logos, banners, illustrations, mockups, photos, textures, diagrams-as-art) with OpenAI gpt-image-2 through the locally installed Codex CLI, using the user's existing ChatGPT login — no API key. Use whenever the user asks to generate, create, draw, or mock up an image, or when a task needs a new image asset that doesn't exist yet.
---

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

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

```bash
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:

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