Universal ImageGen Agent CLI
Image generation and editing from any agent: the imagegen-agent CLI and a skill with the Codex prompt library for compatible APIs
- 234 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Prompts, input images and headers go to the chosen Images API address, and the key is taken from environment variables
- Every real request spends money on the provider side, so the skill requires a dry run before it
Install
- Works in
Manual install
npm install --global universal-imagegen-agentInstalls the `imagegen-agent` CLI. Version 0.1.2 is pinned in the README by a separate command with `@0.1.2`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Prompts, input images and headers go to the chosen Images API address, and the key is taken from environment variables
- Every real request spends money on the provider side, so the skill requires a dry run before it
This is third-party code. Review the repository files before installing.
What it does
The project carries the workflow of the Codex `imagegen` skill over to any agent that can run commands or Python. The `imagegen-agent` CLI creates and edits images through an OpenAI-compatible Images API: you can set your own address, model, headers and extra request parameters. Beside it sits the `universal-imagegen` skill with a decision tree by task type, prompt-writing rules and edit invariants that lock the hero, layout, text and background. The `generate` and `edit` commands take a size, quality, constraints and several input images with a mask, and `batch` processes a JSONL file of jobs in several threads. The `--dry-run` flag checks a request without touching the network, and `--json` prints a machine-readable result. Exit codes are stable: 0 success, 2 configuration or input error, 1 API, network or write failure. A finished file never overwrites an existing one. The key comes only from environment variables, and the CLI deliberately has no `--api-key` option. Configuration can live in `.imagegen.toml`. Node.js and Python interfaces exist for programs. The original Codex skill is preserved unchanged in `upstream/imagegen/`.
Who it is for. Designers, marketers and developers with an agent in Claude Code or Cursor who need image generation on their own key or a compatible gateway.
Good fit when
- An agent in Claude Code or Cursor must draw an illustration or mockup and has no built-in image generator
- The background of a finished image must be replaced without touching the hero, edges and text, so firm edit invariants are needed
- A product catalog needs a batch of images from a JSONL file processed in several threads
- An open model such as Qwen-Image runs on your side and you want to use it through a compatible gateway with a ready prompt library
- A dry run is needed before a paid request to show the prompt, model and file path
Not a fit when
- You need a local Qwen-Image run through Diffusers, ComfyUI or SGLang: there are no direct adapters for them, so a gateway or your own provider is needed
- You have Codex with the built-in `imagegen` tool: the original skill already fits and the CLI adds an extra layer
- Prompts and input images must not go to an external server and there is no trusted compatible service
Example request
First do a dry run: generate a product photo of a ceramic mug for the catalog on a white background at 1536x1024, then create the file with a real requestLimitations
- Only the OpenAI-compatible Images API layer is built in. Local Diffusers, ComfyUI and SGLang for Qwen-Image connect through a compatible gateway or a new provider adapter.
- You need your own key and service address. The default model `gpt-image-2.5-sunburst` is changed with the `IMAGEGEN_MODEL` variable.
- The chosen server receives prompts, input images and headers, so only trusted endpoints fit.
- Python development needs version 3.11 or newer, installed through `uv sync --extra dev`.
How to disable. Remove the CLI with `npm uninstall --global universal-imagegen-agent` and the `universal-imagegen` folder from the agent's skills directory. The `.env` file with the key and `.imagegen.toml` in the project are deleted by hand.
FAQ
How do I install Universal ImageGen Agent?
Run `npm install --global universal-imagegen-agent`, then check `imagegen-agent --version`. Without a global install `npx universal-imagegen-agent generate "A ceramic mug" --dry-run --json` works.
How do I connect the skill to Claude Code or Cursor?
Run `imagegen-agent install-skill --target /path/to/skills`, giving the agent's skills directory. By default the skill goes to `$CODEX_HOME/skills/universal-imagegen`, and `--force` replaces an existing copy.
How do I set the key and the service?
Set `IMAGEGEN_API_KEY`, `IMAGEGEN_BASE_URL` and `IMAGEGEN_MODEL` in the environment or in `.env`. The project supports any compatible Images API, and `imagegen-agent config --json` shows the configuration with the key masked.
How do I edit a finished image?
The command `imagegen-agent edit --image input.png --prompt "Change only the background" --constraints "keep the subject unchanged" --out result.png` edits the file under the given constraints. A mask and several images are supported too.
Can I connect Qwen-Image?
Yes, through an OpenAI-compatible gateway deployed over the model or through a new provider adapter. Direct adapters for Diffusers, ComfyUI and SGLang are not built into the project yet.
Discussion
No questions or reviews yet.
Related
CLI toolsA skill and CLI for generating and editing images with GPT Image 2 and 2.5 plus a library of ready prompts
A set of skills for agents to generate and edit images, video and audio through the muapi.ai service and muapi-cli
Claude Image (GPT Image 2)
claude-image
A skill teaching agents to work with GPT Image 2. OpenAI API access is needed and it is unavailable from Russia without workarounds
A Rust skill and CLI for agents to generate and edit images with GPT Image 2, make transparent PNGs and answer in JSON.
A Python script calls the Agnes AI API for text, images and video from a prompt, a photo or keyframes, and polls for the result
A plugin that draws and edits images in Claude Code through the built-in image_gen of local Codex on a ChatGPT login, no API key.
README in short
The document explains the project's origin from the Codex skill and lists what it offers. Then come the directory structure, installation through npm and pnpm, API setup, command examples, the agent contract, Node.js and Python interfaces and license notes.
README badge
Original SKILL.md
--- name: "universal-imagegen" description: "Bring the Codex imagegen workflow, prompt engineering, use-case taxonomy, edit invariants, and prompt library to any general-purpose agent, then generate or edit raster images through a configurable Images API. Supports OpenAI-compatible services and Qwen-Image deployments exposed through compatible gateways." --- # Universal Image Generation Skill > Adapted on 2026-09-24 from the OpenAI Codex `imagegen` skill. The unmodified > source snapshot is preserved under `upstream/imagegen/`. ## Runtime contract This skill does not assume a host-specific built-in image tool. - Preferred execution: the npm/pnpm-installed `imagegen-agent` CLI. - If the global command is unavailable and package execution is allowed, use `npx -y universal-imagegen-agent` or `pnpm dlx universal-imagegen-agent` as the command prefix. - Reuse the bundled Codex-derived prompt library and workflow regardless of which compatible image model serves the request. - Machine-readable execution: always add `--json`. - Safe validation: run with `--dry-run` before a costly or destructive retry. - Credentials: read from environment variables only. Never ask a user to paste a complete API key into chat and never pass a key on the command line. - API portability: model, base URL, headers, and API-key environment variable are configurable. Do not assume one provider's model catalog. - Open models: Qwen-Image and similar deployments can be used when exposed through the bundled OpenAI-compatible interface. For native Diffusers, ComfyUI, SGLang, or another protocol, add a provider adapter rather than changing the agent-facing workflow. - Output safety: do not overwrite existing files unless the user explicitly authorizes replacement and `--force` is supplied. ## Installation Install the CLI and this skill together: ```bash npm install --global universal-imagegen-agent imagegen-agent install-skill ``` Or install only the skill without keeping a global package: ```bash npx universal-imagegen-agent install-skill ``` Restart or reload the host agent after installation. The installer defaults to `$CODEX_HOME/skills/universal-imagegen`, or