Codex Image Generation Skill

Generate and edit images via codex exec with the built-in imagegen tool. No OPENAIAPI_KEY required.

Prerequisites

Codex CLI

# Mac / Linux (recommended)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Homebrew
brew install --cask codex

# npm
npm install -g @openai/codex

Verify: codex --version

Reliability rules (MUST follow)

These rules come from real production failures. Skipping them produces silently wrong images.

1. Delete a stale output file BEFORE generating (except in-place

refinement, Mode 3). If the output path already exists, Codex may skip generation entirely and report "already saved" while leaving the old image in place.

``bash rm -f <OUTPUT_PATH> ``

Then phrase the instruction as: "The file <OUTPUTPATH> does not exist yet. You MUST generate a brand-new image using the built-in imagegen tool and save it to that exact path. Do not reuse or copy any previously generated image."

1. Verify the output is fresh after every run. Compare the file's

mtime against when the command started (stat -f %m <OUTPUT_PATH> on macOS). If the mtime is old, the run skipped generation: delete the file and rerun with the MUST-generate phrasing above.

1. Isolate concurrent runs with per-job CODEX_HOME. Parallel

codex exec jobs sharing the default ~/.codex also share ~/.codex/generatedimages/. A job whose generation fails may "recover" by copying the newest file there, which can be ANOTHER job's image, silently writing the wrong picture to the requested path. Therefore: when generating 2+ images, run them in parallel, each with its own isolated CODEXHOME (see "Parallel Generation" below). This removes the shared directory and makes parallelism safe. Never run parallel jobs against the shared default home; if a past run did, visually verify every output and rerun any duplicate solo.

1. Visually inspect every generated image before using it (open/Read

the PNG). Check for: garbled or misspelled text (especially Japanese), clipped labels, overlapping elements, broken or wobbly arrows and lines, pasted-on-looking text boxes. Regenerate until it passes; do not ship an image you have not looked at.

Modes

This skill supports three modes. Claude Code constructs a codex exec command directly — no wrapper script is needed.

Mode 1: Prompt → Image

Generate an image from a text prompt.

rm -f <OUTPUT_PATH>
codex exec \
  -s danger-full-access \
  "The file <OUTPUT_PATH> does not exist yet. You MUST generate a brand-new image using the built-in image_gen tool and save it to that exact path. Do not reuse or copy any previously generated image. Image prompt: <PROMPT>"

Prompt construction

Build the prompt by combining these elements in order:

1. Style (optional): Style: watercolor painting.
2. Subject: the user's description
3. Aspect ratio (optional): Use a wide landscape composition (16:9 aspect ratio).
4. Negative (optional): Avoid: blurry, text, watermark.

Example:

Style: watercolor painting. A mountain landscape at sunset with dramatic clouds.
Use a wide landscape composition (16:9 aspect ratio). Avoid: text, watermark.

Mode 2: Document → Diagram

Pass a large text, Markdown, or PDF file to Codex and have it generate an information-rich infographic or diagram.

rm -f <OUTPUT_PATH>
codex exec \
  -s danger-full-access \
  "Read the file <INPUT_PATH>. Analyze its content thoroughly and create an information-rich infographic/diagram that visually summarizes the key points, structure, and relationships. The file <OUTPUT_PATH> does not exist yet. You MUST generate the image using the built-in image_gen tool and save it to that exact path. Additional instructions: <USER_INSTRUCTIONS>"

• Claude Code reads the document first with the Read tool to understand its

content, then crafts a detailed instruction for Codex.

• For very large documents, Claude Code should summarize the key points and

include them directly in the Codex instruction for better results.

• The user's instructions guide the diagram type (infographic, flowchart,

mind map, concept map, timeline, etc.).

• Follow the "Diagram & infographic quality" section below.

Mode 3: Image Refinement

Pass an existing image to Codex for modification.

codex exec \
  -s danger-full-access \
  "Look at the image at <INPUT_IMAGE_PATH>. Make the following modifications using the built-in image_gen tool: <MODIFICATION_INSTRUCTIONS>. Overwrite the existing file at <OUTPUT_PATH> with the modified image."

• Use for color adjustments, style changes, element additions/removals,

composition tweaks, etc.

• Reference the original image path so Codex can analyze it.
• Do NOT pre-delete the file when refining in place (input == output);

instead say "Overwrite the existing file". If input and output differ, apply Reliability rule 1 to the output path.

Diagram & infographic quality

Diffusion-based generation breaks most often on arrows and lines. Design the composition so there is nothing fragile to break.

Composition rules

• Straight, short arrows only. Never request curved arrows, loop-back

arrows, or long connector lines weaving between elements. Express cycles or bidirectional sync with a small pill label (e.g. 「双方向に同期 ⇄」) instead of a curved arrow.

• No overlapping elements. Give every label generous spacing; ask for

"wide margins on every side" so nothing touches the canvas edge.

• Prefer structures that are hard to break: side-by-side panels, 2x2

card grids, stacked horizontal bars, single-row card flows. Avoid dense networks, swimlanes, and diagrams that need many crossing connectors.

• Keep the element count low; split into two images rather than cramming.

Style lines that work

• Flat diagram:

Crisp flat vector infographic, white background, styled like a clean professional presentation slide. Perfectly straight lines, uniform stroke width, sharp clean edges, generous spacing.

• Graphic recording (grareco):

Warm hand-drawn graphic recording style, black ink pen and colored pencil accents on warm cream paper, rounded hand lettering. Add Avoid: digital flat vector look so the style stays consistent across a series.

Standard Avoid list for diagrams

Avoid: watermark, misspelled text, wobbly lines, blur, curved arrows,
overlapping elements, clipped text, stray marks, decorative dots,
sketchy style, 3D effects, photorealism.

Text accuracy (especially Japanese)

• Quote every string that must appear verbatim (e.g. 「承認ゲート」) and add:

All Japanese text must be spelled exactly as given and legible.

• After generation, zoom in and verify every label: tofu/garbled glyphs,

swapped characters, and clipped endings are the most common failures.

Generated Image Recovery

Codex may save images to <CODEXHOME>/generatedimages/ instead of the requested output path (~/.codex/generatedimages/ for a default-home run; $JOB/generatedimages/ for an isolated parallel job). After running codex exec:

1. Check if the output file exists at the requested path **and has a fresh

mtime** (Reliability rule 2).

1. If not, look for the most recently created file in

~/.codex/generated_images/ and copy it to the requested output path.

# Find the latest generated image
ls -t ~/.codex/generated_images/*.png 2>/dev/null | head -1

Warning: never blind-copy from generated_images/ while multiple
generations are running in parallel — the newest file may belong to a
different job (Reliability rule 3). Visually confirm the content matches
the requested prompt before accepting it.

Multiple Images / Parallel Generation

Default to parallel execution when generating 2+ images. Serial execution is only for retries of a single failed image. Parallelism is safe as long as every job gets its own isolated CODEXHOME (cross-contamination — Reliability rule 3 — only happens through the shared ~/.codex/generatedimages/ directory).

Recipe (verified working on codex-cli 0.148.0)

For each image i, prepare an isolated home and launch the job in the background (use the Bash tool's runinbackground, one call per image):

JOB=<SCRATCHPAD>/codex-job-<i>
mkdir -p "$JOB"
cp ~/.codex/auth.json ~/.codex/config.toml "$JOB/"
rm -f <OUTPUT_PATH_i>
CODEX_HOME="$JOB" codex exec \
  -s danger-full-access \
  "The file <OUTPUT_PATH_i> does not exist yet. You MUST generate a brand-new image using the built-in image_gen tool and save it to that exact path. Do not reuse or copy any previously generated image. Image prompt: <PROMPT_i>"

• auth.json carries the login; config.toml carries user settings.

Copying both into the job home is enough — no re-login needed.

• Launch ALL jobs first, then wait for completions; do not run them one

by one.

• After each job finishes, apply Reliability rules 2 and 4 to its output

(fresh mtime + visual inspection). Recovery lookups for that job go to $JOB/generatedimages/, NOT ~/.codex/generatedimages/.

• If a job fails auth (stale token copy), re-copy a fresh

~/.codex/auth.json into its home and rerun that job alone.

• Delete the job homes (rm -rf <SCRATCHPAD>/codex-job-*) after all

outputs are verified.

Aspect Ratios

The built-in image_gen tool does not accept explicit pixel dimensions.
Aspect ratio and composition are controlled through prompt instructions.

Style Examples

See references/prompts.md for detailed prompting guidance.

Limitations

• No explicit resolution control: Use aspect ratio and composition

prompts to influence output proportions.

• Single image per call: Each codex exec invocation generates one

image.

• Codex CLI required: The codex command must be installed and

authenticated.

• Document diagram quality: Results depend on how well the instruction

conveys the document's structure. For complex documents, Claude Code should pre-summarize key points in the instruction.

• Fragile geometry: curved arrows, long connectors, and dense overlaps

frequently render broken. Design them out (see "Diagram & infographic quality").

Error Handling