codex-image-bridge

Production-grade Codex image_gen bridge for Claude Code. Sandbox-correct, opinionated about quality, and immune to the silent stdin-hang that breaks naive codex exec wrappers.

What this is

Claude Code has no first-party image generation. Codex CLI does — it ships a headless image_gen tool that uses gpt-image-2. This plugin wires that tool into Claude Code as a skill, so when you ask Claude to "generate a hero image" or "make a 1024x1024 sprite," it shells out to codex exec and hands you back the saved file path.

There is already at least one community skill that bridges Codex image_gen into Claude Code. This one is opinionated differently:

• No `--yolo`. Runs in --full-auto with explicit --add-dir extensions for the destination and Codex's image cache. The sandbox stays on.
• `gpt-image-2` only. No silent fallback to gpt-image-1.5. No fallback to the scripts/image_gen.py CLI path. Transparency goes through the chroma-key script with a single retry budget; if that fails, the skill stops and reports rather than degrading model quality.
• Strict output contract. The skill replies with Generated N image(s): and the absolute paths. Nothing else. Predictable for downstream automation.
• Documented gotchas. Two failure modes that silently break the naive version are spelled out in SKILL.md:
• codex exec hangs forever on Reading additional input from stdin... if stdin is a non-tty pipe. The skill closes stdin with </dev/null and forbids heredoc prompt construction.
• $$ in temp-file paths does not survive between Claude Code Bash tool calls (each call spawns a fresh subprocess). The skill uses mktemp and threads the literal path through both calls.
• Portable. No hardcoded usernames or project paths. Resolves output via cwd / git-repo / ~/Downloads fallback. Works on macOS and Linux out of the box; Windows via WSL.

Install

Add this repo as a marketplace, then install the plugin:

/plugin marketplace add RolandOne/codex-image-generation
/plugin install codex-image-bridge@codex-image-bridge-marketplace

After install, run /reload-plugins to activate.

Prerequisites

• Codex CLI installed and codex login completed at least once. No OPENAI_API_KEY needed — auth is Codex's.
• Codex's bundled imagegen system skill, which ships at ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md in recent Codex releases. If you don't have it, upgrade Codex.
• POSIX shell (bash/zsh). Windows users: run from WSL.

Usage

Just ask. The skill activates on raster-image requests:

"generate a 1024x1024 illustration of a foggy mountain pass at sunrise, save to ./assets/"
"draw me a transparent sprite of a coffee cup, 512x512"
"make a hero image for a fintech landing page using @reference.png as style"

It deliberately does not activate for SVG, vector, icon-system extensions, or HTML/CSS/canvas drawings.

Costs

Each image costs you twice:

• The gpt-image-2 generation (billed per image by OpenAI/Codex).
• The Codex agent tokens that drive the call. Roughly ~30k agent tokens per single low-quality image, more for larger sizes or batches. These count against your Codex usage limit.

For batches, prefer one Codex run with a count instruction over N separate runs — per-run agent overhead dominates.

Hard limits

• Will not use gpt-image-1.5. Ever. Including for transparency, including on explicit user request.
• Will not call the OpenAI Images API directly.
• Will not retry automatically on failure. Surfaces Codex's error verbatim and stops.
• Will not modify files under $CODEX_HOME/skills/.system/imagegen/.

Why these choices

The opinionation is the product. If you want a permissive "just generate something, fall back to anything" wrapper, this isn't it — use a different skill. If you want a generation step you can put in a pipeline and trust to either return a gpt-image-2 PNG at the path you asked for or fail loudly, this is it.

Architecture

codex-image-bridge/
├── .claude-plugin/
│   ├── plugin.json          # Plugin manifest
│   └── marketplace.json     # Marketplace catalog (single-plugin)
└── skills/
    └── image-generation/
        └── SKILL.md         # The skill itself

The skill is pure SKILL.md — no Node wrapper, no Python helpers, no companion scripts. Claude Code reads SKILL.md, builds the codex exec invocation per the documented contract, runs it, parses the captured last-message file, and replies. All implementation lives in the prose; the prose is the program.

Contributing

Issues and PRs welcome. Two things in particular:

• If you find another silent failure mode in codex exec (something that hangs, returns success-but-wrong, or sandbox-blocks unexpectedly), please document it in SKILL.md the way the stdin-hang and $$ issues are documented.
• If gpt-image-2 is superseded, the model lock will need to be parameterized rather than just bumped — happy to discuss the design.

License

MIT. See LICENSE.