codex-image

A Claude Code skill that generates and edits images with GPT Image, billed to your ChatGPT subscription. No OPENAI_API_KEY required.

Why

This skill generates images through Codex Responses, billed to your ChatGPT subscription, from a single command in your agent session.

/codex-image "a yellow taxi at night in rain"

→ saves a 1024×1024 PNG to ./generated_images/, ~30s.

Status

v0.2.0 released (2026-08-21). Native model transparency; --transparent no longer needs Pillow. 148 tests passing, and the native path was confirmed live against the real backend (genuine alpha, with a user-requested drop shadow surviving into the alpha channel).

See CHANGELOG.md for what's in this release, SKILL.md for the contract Claude reads, and references/ for the canonical request recipe and prompting cookbook.

Install

The quickest path is the skills.sh CLI, which installs the skill into Claude Code, Codex CLI, Cursor, opencode, and 70+ other agents:

npx skills add nuko-nova-dynamics/codex-image        # project install
npx skills add nuko-nova-dynamics/codex-image -g     # global (all projects)

Manual install (Claude Code):

git clone https://github.com/nuko-nova-dynamics/codex-image
ln -s "$(pwd)/codex-image" ~/.claude/skills/codex-image

Either way, the skill auto-detects Codex CLI's auth at ~/.codex/auth.json. Make sure you're signed in:

codex login

Optional: --format webp and --transparent-mode chroma need Pillow (python3 -m pip install 'Pillow>=10'); everything else, including plain --transparent, is stdlib-only.

Quick start

# Generate
/codex-image "a coffee mug"

# Transparent background (native alpha from the model)
/codex-image "a coffee mug" --transparent

# Edit a reference image
/codex-image "make it blue" --input ./mug.png

# Multi-turn (the agent passes --from-last to reuse the prior generation)
/codex-image "now add steam rising"

# Different size + format
/codex-image "hero banner" --size 2048x1152 --format webp

Full flag reference: scripts/generate.sh --help.

Configuration

Defaults can be overridden via env vars:

export CODEX_IMAGE_OUT_DIR="./assets/"
export CODEX_IMAGE_QUALITY="medium"
export CODEX_IMAGE_FORMAT="webp"
export CODEX_IMAGE_ORCHESTRATOR="gpt-6.1-sol"  # optional; unset follows Codex's default

Recognized env vars: CODEX_IMAGE_SIZE, CODEX_IMAGE_QUALITY, CODEX_IMAGE_FORMAT, CODEX_IMAGE_OUT_DIR, CODEX_IMAGE_ORCHESTRATOR (maps to --orchestrator; unset means Codex's current default model for the account), and CODEX_IMAGE_HOME (state dir, default ~/.codex-image). Each flag-backed variable maps to the flag of the same name in scripts/generate.py.

Stability

This skill sends its requests wherever Codex's own config sends Codex. It reads $CODEX_HOME/config.toml over /etc/codex/config.toml: a custom model_provider gets the request at its base_url with its key (no ChatGPT sign-in needed, so a proxy works); otherwise the request goes to openai_base_url when set, else chatgpt.com/backend-api/codex/responses, authenticated by the auth file Codex maintains. Reading the config needs Python 3.11 or later; on 3.10 the skill stops if a Codex config file exists. A config file that exists but cannot be parsed also stops the run instead of falling back to chatgpt.com. That route is not a public, versioned API: a Codex update that changes token storage, required headers, or version gating can break the skill until it's patched. Treat it as tested-against-current-Codex rather than contractually stable; the durable fallback is the official OpenAI Images API with an OPENAI_API_KEY.

GPT Image 2.5

Request either new variant with --image-model gpt-image-2.5-sunburst or --image-model gpt-image-2.5-flare. The CLI also accepts --quality xhigh and --quality max. These are experimental requests on Codex Responses: the endpoint may override them, and the default still leaves model selection to the endpoint. The sidecar records requested and returned values separately; a model mismatch produces a warning. See compatibility and live checks before relying on a particular model or quality.

Known limitations

• Model and quality requests may be overridden: inspect image_model and resolved_quality in the sidecar. Explicit Sunburst and Flare probes on 2026-09-08 both reported gpt-image-2-codex.
• Transparency is requested in the prompt, not the parameter. background: "transparent" is rejected by this backend, but the model returns real alpha when asked in the prompt with background: "auto" — which is what --transparent does. Verified on opaque subjects; hair, glass, smoke and translucency are untested, so the chroma path survives as --transparent-mode chroma. See ADR-0001.
• No batch: the backend rejects n. Multiple images = multiple invocations.
• No multi-turn via previous_response_id: backend is stateless. Multi-turn is achieved by the agent re-passing the prior image (--from-last / --input, up to 16 references).
• No token refresh: the skill reads Codex CLI's auth.json as-is and never refreshes it. If the access token has expired, run any Codex command (or codex login) to rotate it, then retry.

See tests/ for the full test suite and tests/smoke.sh for end-to-end coverage.

References

• references/api-recipe.md — canonical Codex Responses request shape
• references/prompting-cookbook.md — prompting fundamentals + templates
• references/transparent-image-tips.md — how native transparency works, when it struggles, and the chroma fallback
• CONTEXT.md — glossary; defines the three transports that reach OpenAI image models
• docs/adr/ — architecture decisions

Other agents

npx skills add nuko-nova-dynamics/codex-image handles placement for Codex CLI, Cursor, opencode, and the rest of the skills.sh-supported agents — no manual symlinking needed. The primary tested target is Claude Code; behavior in other agents is community-verified, and cross-CLI fixes are welcome via PR.

Development

# Lint shell scripts
shellcheck scripts/*.sh

# Lint python
ruff check scripts/

# Unit tests (offline, mocked HTTP)
python3 -m pytest tests/ -q

# End-to-end smoke test (real backend, ~6 generations, needs codex login + Pillow)
./tests/smoke.sh

See CONTRIBUTING.md.

License

MIT © 2026 Nuko Nova Dynamics

Bundles remove_chroma_key.py from openai/codex (Apache 2.0, compatible).