name: "chatgpt-imagegen" version: "0.11.0" description: "Generate raster images (PNG/JPEG/WebP) using the user's ChatGPT subscription via a local one-file Python CLI — no OPENAI_API_KEY, no gateway, no daemon. Two backends: web (default) drives the user's logged-in ChatGPT browser so generation runs on the conversation surface and does NOT consume Codex-usage limits; codex is a headless fallback that bills the Codex-usage bucket. Use when an agent needs to create a brand-new bitmap asset for the current project (photos, illustrations, icons, hero banners, mockups, sprites, concept art) and the output should be a bitmap file saved into the workspace. Do not use when the task is better solved by editing existing SVG/vector assets, writing code-native graphics (HTML/CSS/canvas), or extending an established repo icon system. Also use proactively: when authoring a document, blog post, technical proposal, design doc, README, or other long-form explanatory content, propose illustrations for the key concepts and generate them as background tasks — don't wait to be asked for an image."

chatgpt-imagegen — agent skill

A standalone Python CLI that produces images via the user's ChatGPT subscription. No API key, no network service, no extra config. It has two backends that hit different OpenAI usage buckets — pick with --backend.

Backends

Default is auto (--backend auto, or CHATGPT_IMAGEGEN_BACKEND): it tries web first because that spares the Codex-usage limit, and falls back to codex only when web is unavailable — i.e. chrome-use isn't installed, the browser isn't reachable, or chatgpt.com isn't logged in. The two not-set-up cases are handled explicitly:

• Browser not logged in / chrome-use missing → auto silently falls back to codex (a one-line notice prints to stderr). If codex is also not set up, it exits naming both fixes.
• codex not logged in (~/.codex/auth.json absent) → auto still uses web; codex is only the fallback.

Auto does not fall back to codex if web was reachable but the generation itself failed after submitting — that would spend the very bucket auto-mode protects. In that case it errors and tells you to rerun with --backend codex if you want the Codex-usage path. Force a single backend with --backend web or --backend codex.

Prerequisites

For the default web backend: the user must have chrome-use (formerly agent-browser-stealth; older installs expose the same binary as agent-browser / abs) and its extension connected to a Chrome that is signed in to chatgpt.com. chrome-use specifically is required — its real-logged-in-Chrome connect is what passes Cloudflare's bot-detection; a plain headless driver will not. The "Temporary Chat" mode disables image generation, so this backend always opens a regular chat.

Install policy — never install chrome-use for the user

If chrome-use is not installed, do not install it on your own initiative:

1. Generate anyway via the codex fallback (auto mode does this by itself) — the task comes first.
2. Add a single gentle tip to your reply, e.g.: "提示：装上 chrome-use 后，出图会走你已登录的 ChatGPT 浏览器，不消耗 Codex 额度。想配的话我可以一步步带你装好（含浏览器插件）。" — and stop there.
3. Only when the user explicitly says yes, walk them through the guided setup below, step by step, verifying each step before the next.

Guided setup (opt-in only):

# 1. Install the CLI (no npm, no token — provides `chrome-use`)
curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh
# 2. Register the native-messaging host
chrome-use extension install
# 3. Add the Chrome extension, then restart Chrome:
#    https://chromewebstore.google.com/detail/agent-browser-stealth/knfcmbamhjmaonkfnjhldjedeobeafmk
# 4. Sign in to https://chatgpt.com in that Chrome
# 5. Verify: a quick `chatgpt-imagegen "test" --backend web` should print "using current Chrome (relay)"

• Repo: https://github.com/leeguooooo/chrome-use
• The chrome-use skill (chrome-use skills get core) covers the extension-connect flow in depth.

For the codex backend: the user must have run, once, ever:

npm i -g @openai/codex
codex login    # opens browser to sign in to ChatGPT

That writes ~/.codex/auth.json, which the codex backend reads. No OPENAI_API_KEY is required for either backend — and setting one will not help. This is the subscription path, not the API path.

When to use

• The user asks for a new photo, illustration, icon, hero banner, sprite, cover image, infographic, product mockup, concept art, or any other bitmap deliverable for the current project.
• The user is happy with subscription-tier quality (medium quality, no native transparent backgrounds — see Limits below).
• The deliverable is intended to be saved into the repo or build inputs.
• You're authoring long-form or explanatory content — a blog post, technical proposal, design doc, tutorial, postmortem, or README — and a figure would help a concept land. You don't need to be asked: propose the figures and generate them (see Illustrating documents below).

When not to use

• The user wants an SVG icon that matches an in-repo vector set — edit those instead.
• The task is better solved with code (HTML/CSS, canvas, Mermaid, PlantUML).
• The user already has an image on disk and wants to edit it — this skill is generate-only.
• The user explicitly needs true quality=high or background=transparent — the subscription path caps quality at medium and rejects transparent. Tell the user to use the official /v1/images/generations API with their OPENAI_API_KEY for those cases.
• The deliverable will be served to end users (e.g. a public service generating images for visitors) — that violates OpenAI's ToS for personal subscriptions. Refuse and explain.

How to invoke

"<skill-dir>/chatgpt-imagegen" "<prompt>" [options]

When this skill is installed via npx skills add leeguooooo/chatgpt-imagegen -g, the bundled chatgpt-imagegen script sits next to this SKILL.md. Call it by its absolute path — that is the most reliable way and never depends on $PATH. If your agent harness exposes a variable that points to the skill's install directory, use it; otherwise expand the path you read this file from.

If the user has separately put chatgpt-imagegen on $PATH (Option B in the README), you can also just run chatgpt-imagegen "<prompt>" directly.

Useful flags:

The script prints just the saved path on stdout in every mode; the readable progress timeline and any errors go to stderr, so OUT=$(chatgpt-imagegen "..." --quiet) captures only the path while you still see the timeline. Each timeline line is stamped with elapsed seconds ([ 12.3s] generating), so a slow run is legible and a stall is obvious.

Styles

A style is a named, reusable prompt snippet stored in ~/.config/chatgpt-imagegen/styles.json (honours $XDG_CONFIG_HOME). --style NAME appends that snippet to the prompt as a suffix; it changes only the text sent to the model, not the output filename. There is no default style out of the box — generation is unchanged unless the user opts in.

• Apply one for a run: chatgpt-imagegen "..." --style doodle.
• When a project has a consistent look, capture it once and reuse it across the session instead of pasting the same long style text into every prompt: chatgpt-imagegen style add proj "<the house-style sentence>", then pass --style proj per run (or chatgpt-imagegen style use proj to make it the active default).
• chatgpt-imagegen style list shows what's available (the active default is marked *); chatgpt-imagegen style show NAME prints a snippet in full; --no-style skips an active default for one run.
• One built-in style ships: doodle (the deliberately-crude MS-Paint look). Resolution order per run: --no-style > --style NAME > active default > none. An unknown --style fails fast (before any browser/codex work), listing the available names.

Save-path policy

1. Always save into the workspace, never into /tmp, $HOME, or ~/.codex/....
2. If the user named a destination, pass it via -o.
3. If they didn't, pick a sensible subdirectory: assets/, public/, static/, docs/img/, web/img/, assets/brand/, etc. Default to assets/generated/ only if nothing better fits.
4. Don't overwrite existing files unless the user asked. With -o the script overwrites silently; without -o it auto-numbers (name.png, name-2.png).
5. After saving, echo the final path back to the user.

Workflow

1. Clarify the prompt enough to write 1–3 sentences: subject, style, composition, mood, constraints. Don't over-augment when the user's prompt is already specific.
2. Pick size and format based on intended use (see table above).
3. Pick the output path inside the workspace.
4. Run chatgpt-imagegen "<prompt>" -o <path> --size <wxh> --quiet.
5. Inspect the result if you can (e.g. with a view_image tool or by reading the file). If clearly wrong, iterate with a single targeted prompt change — do not loop blindly (each call costs subscription quota).
6. Report the saved path plus the final prompt used.

Illustrating documents

When you're authoring a document, blog post, technical proposal, design doc, or other long-form explanatory content, proactively illustrate the key concepts — you don't need to be asked. The flow:

1. Announce a brief plan first. In one or two lines, say where figures will go and what each depicts (e.g. "I'll add two figures: (1) the request→SSE flow, (2) the token-refresh path."). Then generate — don't wait for approval; the plan is the reader's chance to redirect.
2. Fan out background subagents — one per figure. Each runs the CLI with --quiet -o <path> so stdout is just the saved path; keep writing the prose while they render, and embed each image when it lands. Spawn them as background tasks with your own agent/task tooling — one figure per task, never blocking the writing.
3. Parallelism depends on the user's backend — don't override it. Honour the user's --backend / CHATGPT_IMAGEGEN_BACKEND (default auto). On the web backend, concurrency is 1 — background figures queue and render one at a time (still fine: it's in the background, and it spends no Codex-usage). On codex, up to 4 render in parallel but each bills the metered Codex-usage bucket. Which backend to spend is the user's trade-off, not yours.
4. Choose a style to fit the document's tone. There's no default illustration style. For informal or blog-style explainers, the built-in doodle look fits well — deliberately crude, content-accurate (--style doodle). For polished specs, pick a cleaner look or a style you've defined (see Styles).
5. Don't over-illustrate. At most one figure per major concept; never decorate for its own sake; and never loop generating "variants" of the same figure — that just burns subscription quota. If a figure comes out wrong, change the prompt once and regenerate, don't spray.

Writing figure prompts

A vague prompt yields a useless figure. Make the prompt describe the figure's content, not just name it:

• Spell out the boxes, arrows, labels, layout, and relationships — "an architecture diagram" is too vague; say what's in it and how the parts connect.
• One subject, one concept per figure. Split a busy diagram into two.
• Name the style you want explicitly in the prompt or via --style.
• For the doodle look, remember content accuracy beats polish — it's supposed to look crude and hand-drawn, but the labels and structure must still be readable.

Limits

• Image quality is chosen by the backend; this skill has no --quality flag, and the subscription path does not honour explicit quality requests reliably. Don't promise a specific quality level to the user. If they need explicit quality=high, route them to the official /v1/images/generations API with their own OPENAI_API_KEY.
• background: transparent is not supported on the subscription path.
• A single image typically takes 15–60 s, but large or detailed ones occasionally run 2–3 min. The default --timeout is 300 s to cover this; a genuine hang is caught sooner by the --stall-timeout idle window (default 120 s).
• Per-backend concurrency caps (cross-process, flock slot pool; excess runs queue safely, waiters print "waiting…", and --timeout starts only once a slot is acquired): web = 1 (the page surface rate-limits aggressively — "Too many requests"; also one shared Chrome), codex = 4 (measured safe on Plus, capped so big fan-outs can't trip the account limiter). Override via CHATGPT_IMAGEGEN_WEB_CONCURRENCY / CHATGPT_IMAGEGEN_CODEX_CONCURRENCY (0 = unlimited). For parallel batches use --backend codex + shell & + wait; firing parallel web runs is safe but executes one at a time. Do not loop blindly for "variants of the same prompt" — that just burns quota; iterate on the prompt instead.
• Subscription quota is shared with the user's interactive ChatGPT use. Don't bulk-generate (>10 images / minute sustained) without permission — you'll hit per-day caps.

Error handling

Internals (for maintainers / debugging)

web backend (run_web)

• Shells out to chrome-use against a session-named Chrome tab group.
• Opens a regular https://chatgpt.com/ chat (Temporary Chat disables the image tool).
• Resolves the target ChatGPT Project from inside the authenticated page (undocumented endpoints, probed live): GET /backend-api/gizmos/snorlax/sidebar lists projects (a project is a gizmo with id g-p-…); POST /backend-api/projects {name, instructions} creates one. It then navigates to https://chatgpt.com/g/<g-p-id>/project and submits from that composer, which files the conversation inside the project. Any failure degrades to a plain chat with a stderr warning.
• Submits via keyboard type + Enter — not fill: the composer is a ProseMirror/React contenteditable, and fill mutates the DOM without firing the input events React needs, so the send button stays bound to empty state. A send-button click is the fallback.
• Polls page state via eval: waits until the streaming/stop control is gone AND a brand-new <img> (src matching estuary/content|files/download|oaiusercontent) is present and stable across two reads. The img scan is scoped to main img (the tab's own conversation thread) — ChatGPT pushes an "Image created" toast with a matching thumbnail into any open tab when another conversation finishes an image, and a document-wide scan grabs that sibling's image (issue #7). The generated img is NOT inside [data-message-author-role="assistant"], so <main> is the right scope.
• Downloads the bytes with an in-page fetch(src, {credentials:'include'}) → base64, so the browser's own session cookies authorize the signed asset URL. No tokens leave the browser.

codex backend (run_codex)

• Reads ~/.codex/auth.json for access_token, account_id, refresh_token; reads ~/.codex/version.json for the version header.
• POSTs to https://chatgpt.com/backend-api/codex/responses with tools: [{"type": "image_generation"}], streams the SSE response, base64-decodes the image_generation_call result.
• Auto-refreshes the OAuth token on 401/403 via https://auth.openai.com/oauth/token (client_id=app_EMoamEEZ73f0CkXaXp7hrann); the refreshed token is persisted back to auth.json.

Why the web surface is reachable only through a real browser: the consumer backend-api/* paths are gated by three layers — Cloudflare's edge check, a sentinel proof-of-work (sentinel/chat-requirements + an in-page sentinel/sdk.js that computes the token), and a Cloudflare Turnstile token. Tested empirically: a bare bearer-token request from a residential IP passes the Cloudflare edge and the PoW (CF is IP-reputation-based; the PoW is hashcash-style and replicable offline) — the actual wall is Turnstile, an interactive token a headless client can't forge. And "borrow a browser only for the Turnstile token, then go headless" is self-defeating: the token is single-use and short-lived, so you'd open a browser every request anyway. That's why the web backend drives a genuine logged-in browser; the only true no-browser path is the codex backend (which bills Codex-usage).

Related

• HTTP gateway sibling (for multi-app / SDK-compatible usage): https://github.com/leeguooooo/agent-cli-to-api

chatgpt-imagegen

English | 中文

Generate images using your ChatGPT subscription — no OPENAI_API_KEY needed.

A tiny, zero-dependency Python CLI (and AI-agent skill) — one file, stdlib only — that generates images with your ChatGPT account, on the command line and for any AI agent.

✨ Works on a free ChatGPT account too. The default web backend just drives the normal ChatGPT web chat, where even free-tier users get image generation — so no paid plan, no API key, and no Codex required (subject to the free tier's daily image limit). Paid plans simply get higher limits.

chatgpt-imagegen "a watercolor cat sitting on a windowsill" -o cat.png
# -> saved: cat.png  (812,344 bytes)  size=1024x1024  quality=medium

Why this exists

OpenAI offers image generation in two completely separate ways:

The subscription path is invisible to people who don't use the Codex CLI. It runs on ChatGPT's internal backend-api/codex/responses endpoint as a Responses-API tool, authenticated by the OAuth token written into ~/.codex/auth.json when you run codex login.

chatgpt-imagegen exposes that capability on the command line and to any AI agent — with two backends that hit different parts of your subscription.

Backends

The same subscription meters two separate buckets, and which one you spend depends on where the image is generated:

Default auto tries web first (to spare Codex-usage) and falls back to codex when no logged-in browser is reachable. Force one with --backend web / --backend codex (or CHATGPT_IMAGEGEN_BACKEND).

• Laptop / desktop (Chrome open + signed in) → web — no Codex-usage spent.
• Server / headless agent box → codex — no browser there, so auto falls back on its own.

web generates under whatever account that browser is logged into, which may differ from ~/.codex/auth.json — sign the browser into the account whose bucket you want.

Install

You need Python 3.10+, a ChatGPT subscription, and at least one backend (auto uses whichever is set up, preferring web):

codex backend — npm i -g @openai/codex then codex login (writes ~/.codex/auth.json).

web backend — chrome-use (formerly agent-browser-stealth; it drives your real logged-in Chrome via an extension, which is what passes Cloudflare + ChatGPT's anti-bot check) connected to a Chrome signed in to chatgpt.com:

curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh
chrome-use extension install
# then: add the Chrome extension → restart Chrome → sign in to chatgpt.com

Extension: Chrome Web Store. Older installs exposing the binary as agent-browser / abs keep working — the CLI accepts both names.

No chrome-use? Nothing breaks and nothing gets installed behind your back: auto mode falls back to codex and prints a one-line tip that installing chrome-use makes generation cost no Codex-usage.

Option A — for AI agents (recommended)

Install via skills.sh — works with Claude Code, Codex Agent, Cursor, OpenClaw, etc.:

npx skills add leeguooooo/chatgpt-imagegen -g

This drops both the agent instructions (SKILL.md) and the CLI itself into your agent's skill directory. Just ask any compatible agent: "画一张 xxx" / "generate a hero banner for the README".

Option B — standalone CLI

git clone https://github.com/leeguooooo/chatgpt-imagegen
cd chatgpt-imagegen
chmod +x chatgpt-imagegen
./chatgpt-imagegen "a tiny pixel-art mushroom"

Or put it on your $PATH:

sudo install chatgpt-imagegen /usr/local/bin/chatgpt-imagegen

That's the entire setup. No pip install, no virtualenv, no daemon.

Usage

chatgpt-imagegen "<prompt>" [options]

Examples:

# Default → assets/generated/<slugified-prompt>.png
chatgpt-imagegen "watercolor cat"

# Pick the path
chatgpt-imagegen "logo for a coffee shop, vector style" -o brand/logo.png --size 1024x1024

# Landscape hero banner
chatgpt-imagegen "moody mountain sunset" -o web/hero.png --size 1536x1024

# Use in a shell pipeline
OUT=$(chatgpt-imagegen "icon" --quiet)
echo "saved to $OUT"

Styles

A style is a named, reusable snippet of prompt text. Apply one with --style NAME and it's appended to your prompt as a suffix — so --style doodle turns a cat into a cat, drawn as a deliberately crude doodle …. Styles live in a small JSON file (~/.config/chatgpt-imagegen/styles.json, honouring $XDG_CONFIG_HOME), seeded on first use with one built-in style, doodle — the deliberately-awful MS-Paint look the example below is drawn in.

There is no default style out of the box — nothing