Codex ImageGen Bridge

Generate AI images from Claude Code by delegating to Codex CLI's built-in imagegen.imagegen tool (powered by OpenAI gpt-image-2). This avoids the need for a separate OPENAIAPI_KEY — Codex uses its own authentication.

How it works

Claude Code has no built-in image generation tool, but Codex CLI does. This skill bridges the gap:

Claude Code  →  codex exec (Bash)  →  Codex's image_gen.imagegen  →  image file  →  Claude Code reads it

Prerequisites

Before generating, verify Codex is ready:

codex --version 2>/dev/null

If Codex is not installed, tell the user to install it:

npm install -g @openai/codex

Then check authentication:

codex features list 2>/dev/null | grep image_generation

If not authenticated, the user needs to run codex login interactively.

Core command pattern

codex exec \
  --json \
  --skip-git-repo-check \
  --ephemeral \
  -o /tmp/codex-imagegen-lastmsg.txt \
  "<prompt instructions>"

Flags explained:

• --json — output JSONL event stream (structured, parseable)
• --skip-git-repo-check — allow running outside a git repo
• --ephemeral — don't persist the session (stateless, clean)
• -o <file> — write Codex's final text message to a file

Image generation workflow

Step 1: Compose the prompt for Codex

The prompt sent to codex exec should explicitly instruct Codex to use its image_gen.imagegen tool. Codex is smart but may default to writing code if the prompt is ambiguous.

Template:

Use the image_gen.imagegen tool to generate <description of image>.
After generation, copy the result image to <output_path>.

Key rules for the prompt:

• Always mention image_gen.imagegen by name — this prevents Codex from writing Python to create the image manually
• Always specify a concrete output path for Codex to copy the image to (e.g., /tmp/codex-output.png)
• Include style, composition, lighting, and constraint details directly in the prompt
• For text in images, spell out the exact text and ask for verbatim rendering

Step 2: Run the command

codex exec --json --skip-git-repo-check --ephemeral \
  -o /tmp/codex-imagegen-lastmsg.txt \
  "Use the image_gen.imagegen tool to generate a photorealistic image of <description>. After generation, copy the result to /tmp/my-image.png"

Timeout: image generation typically takes 15–60 seconds. Set Bash timeout to 180000ms (3 minutes) to be safe.

Step 3: Verify and retrieve

After codex exec completes:

1. Check if the output file exists:

``bash ls -lh /tmp/my-image.png ``

1. If the file doesn't exist at the specified path, check Codex's default output directory:

``bash ls -lt ~/.codex/generatedimages/ | head -5 ` Then find and copy the most recent image: `bash find ~/.codex/generatedimages/ -name "ig_*.png" -mmin -5 -type f | sort | tail -1 ``

1. Read the image to show the user:

`` Read: /tmp/my-image.png ``

Proxy handling

If the user's environment uses a proxy (common in China), prepend proxy environment variables:

HTTP_PROXY=http://127.0.0.1:7897 \
HTTPS_PROXY=http://127.0.0.1:7897 \
ALL_PROXY=http://127.0.0.1:7897 \
codex exec --json --skip-git-repo-check --ephemeral \
  "..."

Check for proxy by looking at shell environment:

echo $HTTP_PROXY $HTTPS_PROXY $ALL_PROXY

If any proxy variable is set, inherit it. If the user has a proxy wrapper function for codex (check which codex or type codex), the proxy may already be handled.

Prompt engineering

Structure the image prompt for best results:

Use the image_gen.imagegen tool to generate an image with these specifications:

Use case: <product-mockup | photorealistic-natural | illustration-story | ui-mockup | ads-marketing | logo-brand | stylized-concept | etc.>
Primary request: <what the user wants>
Style/medium: <photography | illustration | 3D render | watercolor | etc.>
Composition/framing: <wide shot | close-up | top-down | centered | etc.>
Lighting/mood: <natural light | studio | dramatic | warm golden hour | etc.>
Color palette: <any color preferences>
Constraints: <no text | no watermark | specific aspect ratio | etc.>
Avoid: <things to exclude>

After generation, copy the result to <output_path>.

Only include fields that are relevant. A simple request like "generate a cat photo" doesn't need all fields — just add enough detail to get a good result.

Prompt tips

• Be specific about the subject and setting
• Include intended use (landing page hero, app icon, social media post) to set the right polish level
• For photorealism, use camera language: "85mm lens", "shallow depth of field", "soft studio lighting"
• For text in images, quote the exact string and spell out tricky words letter-by-letter
• Always include "no watermark" unless one is desired

Transparent background images

For images that need transparency (logos, stickers, sprites, cutouts):

1. First try the chroma-key approach — ask Codex to generate on a solid color background:

`` Use image_gen.imagegen to generate <subject> on a perfectly flat solid #00ff00 chroma-key background. The background must be one uniform color with no shadows, gradients, texture, or lighting variation. Keep the subject fully separated from the background with crisp edges. After generation, copy to /tmp/subject-green.png ``

1. Then remove the background locally using Codex's bundled helper:

``bash python "${CODEXHOME:-$HOME/.codex}/skills/.system/imagegen/scripts/removechromakey.py" \ --input /tmp/subject-green.png \ --out /tmp/subject-transparent.png \ --auto-key border \ --soft-matte \ --despill ` This requires Pillow. On macOS with system Python (PEP 668), use a temp venv: `bash python3 -m venv /tmp/pillow-env && /tmp/pillow-env/bin/pip install pillow /tmp/pillow-env/bin/python "${CODEXHOME:-$HOME/.codex}/skills/.system/imagegen/scripts/removechromakey.py" \ --input /tmp/subject-green.png --out /tmp/subject-transparent.png \ --auto-key border --soft-matte --despill ``

1. If chroma-key removal produces poor results (hair, fur, glass, smoke), inform the user that true native transparency requires Codex's CLI fallback with gpt-image-1.5, which needs OPENAIAPIKEY set separately.

Image editing

To edit an existing image, first copy it to a path Codex can access, then instruct Codex:

Use image_gen.imagegen to edit the image. The image to edit is at /tmp/source-image.png.
Edit instructions: <what to change>.
Keep everything else unchanged.
After editing, copy the result to /tmp/edited-image.png.

For Codex to "see" a local image, you may need to instruct it to use view_image first:

First use view_image to look at /tmp/source-image.png, then use image_gen.imagegen
to edit it: <edit instructions>. Copy the result to /tmp/edited-image.png.

Batch generation

For multiple images or variants, include all requests in a single prompt:

Generate the following images using image_gen.imagegen (one call per image):

1. A sunset landscape — save to /tmp/batch/sunset.png
2. A mountain lake — save to /tmp/batch/lake.png  
3. A forest path — save to /tmp/batch/forest.png

Create the /tmp/batch/ directory first.

Parsing JSONL output

The codex exec --json output is a JSONL stream. Useful event types:

• thread.started — session began
• item.completed with type: "command_execution" — a shell command ran (look for cp commands to find the output path)
• item.completed with type: "agent_message" — Codex's text response
• turn.completed — includes token usage

The imagegen tool call itself is invisible in JSONL — it happens server-side. But the image file is written to ~/.codex/generatedimages/<session-id>/ig_*.png and Codex will cp it if instructed.

Error handling

Output file management

• Default Codex output: ~/.codex/generatedimages/<session-id>/ig<hash>.png
• Recommended target for temp/preview: /tmp/codex-imagegen/
• For project assets: copy into the project directory with a descriptive filename
• Don't leave project-referenced images only in ~/.codex/ — always copy to the project

Limitations

• Image generation uses Codex's OpenAI quota (tied to the user's Codex/OpenAI account)
• No fine-grained control over image dimensions from Claude Code (Codex defaults to auto/1024x1024)
• The image_gen tool call is opaque — you can't see the exact API parameters in JSONL
• Editing requires Codex to "view" the image first, which adds a step
• Each codex exec call is ephemeral — no conversation history between calls