giulioco/codex-imagegen

codex-imagegen

Generate and edit bitmap images from Claude Code by driving Codex's built-in image_gen tool through a one-shot codex exec run.

Why this works (the mechanism)

Codex ships a $imagegen skill with two modes:

1. Built-in image_gen tool (this skill uses it) — runs against Codex's own backend using the user's ChatGPT/Codex login (~/.codex/auth.json). No OPENAI_API_KEY required, no per-image API billing. It's the default Codex mode.
2. CLI fallback (scripts/image_gen.py) — hits the OpenAI Image API directly, needs OPENAI_API_KEY. This skill does not use it.

The built-in tool is internal to Codex's agent runtime — there is no codex image subcommand. But a headless codex exec "<prompt>" run can invoke it. The wrapper script builds a tightly-scoped prompt that forces Codex to use only the built-in tool, runs codex exec, then locates the PNG Codex just wrote under $CODEX_HOME/generated_images/ and copies it into the working directory with a clean filename.

Source it wraps: ~/.codex/skills/.system/imagegen/ (Codex's installed skill).

Prerequisites

• codex CLI on PATH and logged in (codex login). Verify: codex login status or just run a generation — the wrapper reports a clear error if Codex isn't authed.
• No API key needed. The wrapper explicitly tells Codex not to use the API/CLI fallback.

Usage

The wrapper lives at scripts/codex_imagegen.py (resolve its absolute path relative to this SKILL.md).

Generate

python3 scripts/codex_imagegen.py generate \
  --prompt "a minimal hero image of a ceramic coffee mug, soft studio lighting, lots of negative space" \
  --out ./hero.png

• --out accepts a file (./hero.png), a directory (./images/ → auto-named from the prompt), or is omitted (lands in cwd, named from a slug of the prompt).
• -n 3 generates 3 distinct images (one built-in call each). With -n>1 and a file --out, outputs are suffixed -1, -2, -3.
• Existing files are never overwritten unless --force; otherwise a -v2 sibling is written.

Edit an existing local image

python3 scripts/codex_imagegen.py edit \
  --image ./photo.png \
  --prompt "change the background to a warm sunset gradient; keep the subject unchanged" \
  --out ./photo-sunset.png

The wrapper makes Codex load the local file with its built-in view_image tool first, then edit it. Default output (no --out) is <name>-edited.png in cwd.

Output

On success the script prints [codex-imagegen] wrote <path> lines and then the absolute path(s) on their own line(s). Each run takes ~30–90s (it spins up a Codex agent). Report the final path(s) to the user and, when useful, Read the PNG to show it inline.

Prompting guidance

The built-in tool renders well from a structured spec. Shape the user's request into: scene/backdrop → subject → details → constraints, plus intended use for the right polish level.

• Already-detailed prompt → normalize it, don't pad it.
• Generic prompt → add only tasteful, materially-helpful detail (composition, lighting, intended use). Don't invent extra subjects, brands, slogans, or palettes the user didn't imply.
• Quote exact in-image text verbatim and specify placement/typography.
• For edits, state invariants every time: "change only X; keep Y unchanged."
• For many distinct assets, issue separate generations — don't ask for one image "containing" all of them.

Use cases the built-in tool handles well: photorealistic scenes, product mockups, UI mockups, infographics, ads/marketing creatives, logos, illustrations, stylized concept art, and edits (object swap, lighting/weather, background replace, restyle, composite).

Transparent backgrounds

The built-in tool has no native transparency control. For a transparent cutout of a simple opaque subject: generate it on a flat #00ff00 chroma-key background (#ff00ff if the subject is green), then key it out locally with Codex's helper:

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

Truly hard cases (hair, fur, glass, smoke, soft shadows) need real transparency, which only the OpenAI-API CLI fallback (gpt-image-1.5 --background transparent) provides — that requires OPENAI_API_KEY and is out of scope for this skill. Tell the user if a request needs it.

When NOT to use

• Vector/SVG icon or logo systems already in the repo — edit those natively.
• Diagrams/wireframes better built deterministically in HTML/CSS/canvas/SVG.
• The user explicitly wants the OpenAI Image API directly with size/quality/fidelity flags — that's Codex's CLI fallback path, not this one.

Troubleshooting

• "codex exec exited non-zero" / auth error → run codex login.
• "Could not find any generated image" → Codex may have declined the prompt or chosen another tool. The wrapper falls back to diffing $CODEX_HOME/generated_images/ before/after the run, so this usually only happens on refusal or a true failure; check the printed Codex output.
• Slow → normal; each run boots a Codex agent. Use --timeout to extend (default 300s).