# Codex Imagegen > Generate AI images (photos, illustrations, concept art, product shots, game assets, UI mockups, posters, textures, sprites, stickers) by delegating to Codex CLI's built-in image_gen tool. Use this skill whenever the user asks to generate, create, or make any AI-generated bitmap image in Claude Code — including requests like 'generate an image', 'create a photo of', 'make an illustration', 'design a poster', 'draw a picture', 'generate a product shot', 'create concept art', 'make a logo', 'create a thumbnail', 'generate a hero image', or any visual asset request that needs AI image generation rather than code-based SVG/HTML. Also trigger when the user says '生成图片', '画一张图', '做个海报', '生成一张照片', '帮我画', '生成插画'. Do NOT trigger for editing existing SVG/vector files, creating HTML/CSS layouts, or generating diagrams/flowcharts (those are better handled by code or other tools). - Skill: `nangongwentian-fe/codex-imagegen` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add nangongwentian-fe/codex-imagegen` - Raw SKILL.md: https://api.skillmd.com/api/skills/nangongwentian-fe/codex-imagegen/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: nangongwentian-fe (https://skillmd.com/u/nangongwentian-fe) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nangongwentian-fe/codex-imagegen --- # Codex ImageGen Bridge Generate AI images from Claude Code by delegating to Codex CLI's built-in `image_gen.imagegen` tool (powered by OpenAI gpt-image-2). This avoids the need for a separate `OPENAI_API_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: ```bash codex --version 2>/dev/null ``` If Codex is not installed, tell the user to install it: ```bash npm install -g @openai/codex ``` Then check authentication: ```bash codex features list 2>/dev/null | grep image_generation ``` If not authenticated, the user needs to run `codex login` interactively. ## Core command pattern ```bash codex exec \ --json \ --skip-git-repo-check \ --ephemeral \ -o /tmp/codex-imagegen-lastmsg.txt \ "" ``` 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 ` — 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 . After generation, copy the result image to . ``` 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 ```bash 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 . 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 ``` 2. If the file doesn't exist at the specified path, check Codex's default output directory: ```bash ls -lt ~/.codex/generated_images/ | head -5 ``` Then find and copy the most recent image: ```bash find ~/.codex/generated_images/ -name "ig_*.png" -mmin -5 -type f | sort | tail -1 ``` 3. 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: ```bash 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: ```bash 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: Primary request: Style/medium: Composition/framing: Lighting/mood: Color palette: Constraints: Avoid: After generation, copy the result to . ``` 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 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 ``` 2. Then remove the background locally using Codex's bundled helper: ```bash python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.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 "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \ --input /tmp/subject-green.png --out /tmp/subject-transparent.png \ --auto-key border --soft-matte --despill ``` 3. 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 `OPENAI_API_KEY` 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: . 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: . 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 `image_gen` tool call itself is invisible in JSONL — it happens server-side. But the image file is written to `~/.codex/generated_images//ig_*.png` and Codex will `cp` it if instructed. ## Error handling | Symptom | Cause | Fix | |---------|-------|-----| | `codex: command not found` | Codex not installed | `npm install -g @openai/codex` | | Empty agent message, no image file | Auth expired or network issue | User runs `codex login` | | Codex writes Python instead of using image_gen | Prompt didn't mention the tool | Explicitly say "use image_gen.imagegen tool" | | Image in `~/.codex/generated_images/` but not at target path | Codex didn't cp | Manually find and copy the latest image | | Timeout | Slow network or large image | Increase Bash timeout to 300000ms | | Proxy errors | Network blocked | Set HTTP_PROXY/HTTPS_PROXY env vars | ## Output file management - Default Codex output: `~/.codex/generated_images//ig_.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