Image Use

image-use — agent skill

A standalone Python CLI that produces images via the user's existing subscriptions — ChatGPT by default, Codex as fallback, Gemini on request. (Formerly chatgpt-imagegen; that command still works as an alias for image-use.) No API key, no network service, no extra config. It has two OpenAI backends that hit different usage buckets — pick with --backend — plus two opt-in Google/Gemini backends for users who also have a Gemini subscription.

Backends

| Backend | Surface | Usage bucket | Needs | Speed | | --- | --- | --- | --- | --- | | web | Drives the user's logged-in ChatGPT browser (via chrome-use, formerly agent-browser-stealth; older installs expose the same binary as agent-browser/abs) and generates in a regular chat — the same surface as typing in the app. Its real-Chrome connect is what clears Cloudflare + the sentinel proof-of-work a plain/headless client can't. | ChatGPT conversation — does not consume the metered Codex-usage limit. Works on any account, including free tier (subject to its daily image cap). | chrome-use installed and its extension connected to a Chrome signed in to chatgpt.com. | ~30–60 s; each run's chat is filed under a ChatGPT Project (default imagegen, auto-created) instead of littering the history. | | codex | Headless POST to chatgpt.com/backend-api/codex/responses with the image_generation tool, reusing ~/.codex/auth.json. | Codex-usage (metered — this is the bucket the user usually wants to spare). | codex login (writes ~/.codex/auth.json). | Fast; no browser, no history. |

Default is auto (--backend auto, or IMAGE_USE_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.

Gemini backends (opt-in — auto never picks them)

For users who also have a Google/Gemini subscription. Both drive a Google account, not OpenAI.

| Backend | Surface | Needs | Speed | | --- | --- | --- | --- | | gemini | Drives a logged-in gemini.google.com browser via chrome-use — the browser analogue of web. | chrome-use, plus a Chrome profile signed in to a subscribed Google account. | ~11–24 s | | agy | The Antigravity CLI (agy) run headless — the analogue of codex. | agy on PATH. Passes --dangerously-skip-permissions by default because headless agy cannot prompt for tool permissions; --no-agy-yolo opts out if the user maintains their own permissions.allow rules. | ~14–25 s |

Their quotas are separate — measured, not assumed: agy returned "Image generation model quota (gemini-3.1-flash-image) has been exhausted (429)" while a --backend gemini run on the same Google account succeeded seconds later. So each is a genuine fallback for the other, and a quota error from one names the other in its message.

Neither is ever chosen by auto. Deliberate: they hit a different vendor and account, and their output differs in ways a caller would notice. Ask for them by name.

Behaviour worth knowing before recommending one:

• Visible watermark. gemini text-to-image results carry the Gemini "sparkle" glyph, fixed at 65 px in from the bottom-right corner (measured identical across 5 runs at 1024×559). Image-to-image results do not. agy results have no visible mark.
• Both are watermarked invisibly regardless. agy output carries a Google-signed C2PA manifest whose own description reads "Applied imperceptible SynthID watermark". The SynthID signal is in the pixels and survives any re-encode.
• gemini keeps the C2PA manifest on current chrome-use. Gemini renders results from a blob: src, which in-page fetch() still cannot read; chrome-use download-url now resolves the blob inside the page and writes the original bytes to disk, so the signed manifest survives. Older chrome-use rejected blob: outright, leaving only a canvas re-encode — that path is still the fallback and still strips metadata, and the run prints a note naming the upgrade when it has to take it. agy copies the file, so its manifest always survives.
• --size controls the aspect ratio on gemini, not the pixel count. The chat surface has no size widget, so the ratio is requested in words — and honoured: asking square returned 1024×1024, asking 3:2 returned 1024×687, asking 2:3 returned 687×1024. What you cannot pin is the absolute resolution. With nothing requested Gemini defaults to 16:9, so the backend always asks for something (square when --size is auto). Real dimensions land in the run meta.
• The dedicated image model is selected automatically. Before generating, the backend switches the composer to Gemini's image tool, which reports "generated using Nano Banana 2" — otherwise the prompt is answered by whatever chat model is active (seen: Flash-Lite). Best-effort: if the menu moved, the run continues on the chat default rather than failing. --no-gemini-image-tool skips the attempt. It does not remove the watermark or change the default ratio — both were checked against it directly.
• Pin the profile. Nearly every Chrome profile is signed in to some Google account, and the cookie says nothing about which one holds the subscription — a probe run landed on an account whose "Google AI Pro subscription has expired" page has no composer at all. Set --gemini-profile / IMAGE_USE_GEMINI_PROFILE. doctor warns when nothing is pinned.

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 `image-use "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 defaults (auto quality, no guaranteed transparency — see Limits below), or will opt into --backend codex with --image-model / --quality / --background when they need more control.
• 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](#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 wants an existing image modified in place — retouching, cropping, text/logo removal, upscaling, background knock-out. This skill always renders a new image; it cannot return an edited copy of the original's pixels. (Passing an image as a reference with --ref / --style-ref / --composition-ref is supported and encouraged — that's re-generation guided by the image, not editing it.)
• The user needs a guaranteed quality=high or a true transparent background. --backend codex --quality high --background transparent requests both, but the subscription backend may normalise them (the saved line prints what was actually used). For a guarantee, tell the user to use the official /v1/images/generations API with their OPENAI_API_KEY.
• 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

"/image-use" "" [options]

Call the script by its absolute path next to this SKILL.md — that's the most reliable way and never depends on $PATH. If your agent harness exposes a variable pointing to the skill's install directory, use it; otherwise expand the path you read this file from.

First: self-heal a missing CLI

**npx skills add copies only the markdown — it often does not drop the image-use script next to this file.** So before the first run, check that the CLI exists and fetch it if absent. It's a single self-contained, pure-stdlib Python file (no pip, no deps), so the heal is one curl:

CLI="/image-use"   # same directory as this SKILL.md
if [ ! -x "$CLI" ]; then
  curl -fsSL https://raw.githubusercontent.com/leeguooooo/image-use/main/image-use -o "$CLI" \
    && chmod +x "$CLI"
fi
"$CLI" --version   # confirm it runs (needs python3 ≥ 3.10 on PATH)

Do this silently — don't ask the user. If the curl fails (offline/proxy), fall back to git clone https://github.com/leeguooooo/image-use and run image-use/image-use, or tell the user to install it standalone (see README). Only python3 is required to run it.

If the user has separately put image-use on $PATH (Option B in the README), you can also just run image-use "" directly and skip the self-heal.

Old name. Installs from before the rename have a chatgpt-imagegen script (and skill directory); it is now a thin alias that runs image-use with the same arguments and exit code, so either name works. Environment variables are IMAGE_USE_*; each still accepts its old CHATGPT_IMAGEGEN_* spelling, and the new name wins when both are set.

Useful flags:

| Flag | When to use | | --- | --- | | --backend auto \| web \| codex \| gemini \| agy | auto (default) prefers web and falls back to codex only when the browser is unavailable/not-logged-in; web forces the logged-in-browser path (spares Codex-usage); codex forces the headless path (bills Codex-usage); gemini and agy use a Google account instead and are never picked by auto (see [Gemini backends](#gemini-backends-opt-in--auto-never-picks-them)). Also settable via IMAGE_USE_BACKEND. | | --gemini-profile NAME | (gemini backend) Chrome profile to drive, overriding --profile. Worth setting — auto-detection cannot tell which Google account holds the subscription. Also IMAGE_USE_GEMINI_PROFILE. | | --no-gemini-image-tool | (gemini backend) skip switching the composer to the dedicated image model (Nano Banana 2). Rarely wanted — the switch is already best-effort. | | --no-agy-yolo | (agy backend) don't pass --dangerously-skip-permissions. Only use it if the user has their own permissions.allow rules — otherwise every headless run fails. | | --profile auto \| relay \| NAME | (web) Which Chrome profile to drive. auto (default): use the open Chrome if it's logged in, else auto-switch to a profile that is (detected offline from the cookie DB, read-only). relay: only the open Chrome. "Profile 3": that profile. Note: logged in ≠ able to generate — a free-tier account can still hit its daily image cap. | | --session NAME | (web) Drive a named Chrome tab group instead of the shared chatgpt-web session. Rarely wanted: the default is shared ON PURPOSE so the whole machine keeps ONE chatgpt.com tab. | | --project NAME | (web) ChatGPT Project to file the run's conversation under — matched by exact name, created automatically if absent, reused if present. Default imagegen (or IMAGE_USE_PROJECT). Pass --project "" for a plain top-level chat. If the project step fails, the run warns and continues in a plain chat — it never blocks generation. | | --keep-tab | (web) Leave the ChatGPT tab open after generating (default closes it). Useful for debugging. Implies --keep-conversation. | | --keep-conversation | (web) Keep the ChatGPT conversation after generating. Default deletes it (PATCH is_visible:false) so the run leaves no history — it's filed under the project only transiently. Also IMAGE_USE_KEEP_CONVERSATION=1. | | -o PATH | Always use when you know where the file should go in the repo. | | --model NAME | (codex only) The driver model that reads the prompt and calls the image tool — not the image model (the server renders with its own, observed gpt-image-2-codex). It bills the metered Codex bucket, so keep it on a fast/affordable Codex-account model: default gpt-5.6-luna, alternatives gpt-reserve, gpt-5.3-codex-spark. A frontier coding model (gpt-6-astra, …) just burns the bucket. Unsupported models auto-fall-back to gpt-5.5. Also IMAGE_USE_MODEL. | | --size 1024x1024 | Square icons / logos (verified) | | --size 1536x1024 | Landscape hero banners, social cards (verified) | | --size 1024x1536 | Portrait covers, mobile splashes (verified) | | --size 3840x2160 or similar | 4K landscape (forwarded as-is; backend may reject — fall back to a smaller verified size on failure) | | --format webp | Smaller files for web assets | | --image-model MODEL | (codex only) Pick the GPT Image model: gpt-image-2.5-sunburst (precise editing) or gpt-image-2.5-flare (fast, high quality); older gpt-image-2 / gpt-image-1.5 / gpt-image-1 / gpt-image-1-mini also work. Unset = the backend's own default. Also IMAGE_USE_IMAGE_MODEL. | | --quality LEVEL | (codex only) low \| medium \| high \| xhigh \| max — the last two require a 2.5 model (--image-model). A request, not a guarantee; verify with the quality= the tool prints on save. Al

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: leeguooooo
• Source: leeguooooo/image-use
• License: MIT

Install and usage instructions live in the source repository linked above.