Overview

A ChatGPT subscription comes with image generation, but from the terminal the usual way to get at it is to ask the Codex agent to draw something. codex-img skips the agent. It sends your prompt to the same image endpoint the Codex CLI uses, with the login codex login already saved, and writes the image to disk. That's one request per image, and your prompt reaches the image model word for word.

It's built for scripts and coding agents as much as for people. Paths go to stdout, progress to stderr, --json gives one line of metadata per image, and each kind of failure has its own exit code.

What it does

Generate and edit: codex-img "a red fox in snow, flat vector" -o fox.png. Add up to five -i reference images to edit or combine them.
Several at once: -n 4 runs four requests in parallel.
PNG, JPEG or WebP: the backend returns PNG, and codex-img converts it locally. WebP is lossy by default, and a 946 KB image came out at 7.5 KB; --lossless keeps every pixel. Every PNG it writes is also recompressed losslessly, which roughly halves the file.
Palette PNGs: -c 64 reduces the image to 64 colours, like pngquant, and keeps transparency. A 946 KB icon came out at 8 KB.
codex-img convert: the same conversion for images you already have. It doesn't use your login or quota.
Safe with your login: it only reads ~/.codex/auth.json. It never refreshes or writes tokens, so it can't log Codex out.
Never overwrites an existing file.

For agents

The repository includes an Agent Skill that Claude Code, Codex and other skill-aware agents pick up when a task needs an image. It explains when to spend quota, what to do for each exit code (don't retry a quota or login error, for example), and how to write prompts.

If the binary isn't installed, the skill falls back to a small Python script that uses only the standard library. It has the same flags and output, but writes PNG only. Copying the skill folder is enough to get started.

Install

Download the archive for your platform from the latest release. There are builds for macOS (Apple Silicon and Intel) and Linux (x86-64 and ARM64, fully static). Put codex-img on your PATH, and log in once with codex login using your ChatGPT account. codex-img status checks the login without using any quota.

Format conversion, lossy WebP, palette PNGs and convert are on main and will be in the next release. Until then, build from source with ./scripts/install.sh, which also links the skill into ~/.claude/skills and ~/.codex/skills.

Built with

Rust, as a single ~2 MB binary with no runtime dependencies. It uses ureq for HTTP, the image crate for decoding and JPEG, libwebp for WebP, exoquant for palettes and oxipng for PNG recompression. The skill's fallback script is plain Python 3.9.

This isn't an official API. codex-img calls the backend the Codex CLI uses, so it can break when that backend changes.