codex-imagegen-mcp 0.1.2

package/docs/AUTH.md

@@ -0,0 +1,242 @@
+<p align="center">
+  <img src="assets/banner-auth.jpg" width="100%" alt="Authentication — a travel-poster illustration of a stone gatehouse with its wooden gates open on a desert road, a giant iron key leaning against the wall">
+</p>
+
+# Authentication
+
+How the Codex image tool authenticates, how this server reproduces it, and how you sign in before using it. Every protocol detail was checked against the Codex source at tag `rust-v0.155.0-alpha.16` (the build inside Codex desktop 26.917.51856) and against the live service.
+
+**On this page:** [TL;DR](#tldr) · [Credential sources](#credential-sources) · [Browser sign-in](#browser-sign-in) · [Device-code sign-in](#device-code-sign-in) · [Token storage](#token-storage) · [Refresh](#refresh) · [Request headers](#request-headers) · [Plans and workspaces](#plans-and-workspaces) · [Signing out](#signing-out) · [Troubleshooting](#troubleshooting) · [Security notes](#security-notes)
+
+## TL;DR
+
+> [!TIP]
+> - Image requests go to `https://chatgpt.com/backend-api/codex/images/{generations,edits}` with `Authorization: Bearer <ChatGPT access token>` and `ChatGPT-Account-ID: <workspace id>`.
+> - The token comes from **OpenAI's OAuth server** (`auth.openai.com`) through the **Codex CLI's public client**. Browser sign-in uses authorization code with PKCE; headless machines use OpenAI's device-code variant.
+> - Access tokens live about **10 days** and are renewed with **single-use, rotating** refresh tokens.
+> - The server uses its **own** sign-in, or **borrows** an existing Codex or opencode ChatGPT sign-in **read-only**.
+
+## Credential sources
+
+At every request, the server takes the first source that yields a valid token:
+
+```mermaid
+flowchart LR
+    req(["image request"]):::ink --> own{"own sign-in<br/>auth.json"}:::cream
+    own -- "valid" --> use(["use it"]):::teal
+    own -- "expires within 5 min" --> refresh["refresh under<br/>the shared lock"]:::rust --> use
+    own -- "missing" --> codex{"Codex<br/>~/.codex/auth.json"}:::cream
+    codex -- "token still valid" --> use
+    codex -- "missing or expired" --> oc{"opencode<br/>ChatGPT sign-in"}:::cream
+    oc -- "token still valid" --> use
+    oc -- "missing or expired" --> none(["not signed in:<br/>run login or call sign_in"]):::ochre
+    classDef ink fill:#2A2523,stroke:#9A8C76,color:#E4D9C6
+    classDef rust fill:#A6553B,stroke:#7E3F2B,color:#FFFFFF
+    classDef ochre fill:#D9A05B,stroke:#B5813F,color:#2A2523
+    classDef teal fill:#4E6E63,stroke:#3A544B,color:#FFFFFF
+    classDef cream fill:#E4D9C6,stroke:#A89A80,color:#2A2523
+```
+
+| # | Source | File | Refreshed by this server? |
+|---|---|---|---|
+| 1 | **Own sign-in** (`codex-imagegen-mcp login` or the `sign_in` tool) | `$CODEX_IMAGEGEN_HOME/auth.json`, by default `~/.local/share/codex-imagegen-mcp/auth.json` | **Yes**, automatically, under a cross-process lock |
+| 2 | **Codex** CLI or desktop app | `$CODEX_HOME/auth.json`, by default `~/.codex/auth.json` | **No**, read-only |
+| 3 | **opencode** "ChatGPT Plus/Pro" provider | the `openai` entry in `~/.local/share/opencode/auth.json` | **No**, read-only |
+
+To pin a single source, set `CODEX_IMAGEGEN_CREDENTIALS=own|codex|opencode` (the default is `auto`). `codex-imagegen-mcp status` and the `auth_status` tool show every source and which one is active.
+
+### Why borrowed sign-ins are read-only
+
+> [!IMPORTANT]
+> OpenAI refresh tokens are **single-use**. Every refresh returns a new refresh token and invalidates the old one; reuse fails with `refresh_token_reused`, which Codex handles in `codex-rs/login/src/auth/manager.rs`. If this server refreshed Codex's or opencode's token, that app would later present an already-spent refresh token and be signed out.
+
+So borrowed tokens are used only while their access token is valid, judged by the JWT `exp` claim with a 60-second margin. After that the server moves on to the next source. The owning app renews its own token the next time it runs; Codex, for example, refreshes when fewer than 5 minutes remain. Borrowed files are never written.
+
+Codex users on the `keyring` credential store have no `auth.json`, so for them this source reports "not signed in". Use `login` instead.
+
+## Browser sign-in
+
+```bash
+codex-imagegen-mcp login
+```
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as You
+    participant CLI as codex-imagegen-mcp
+    participant B as Browser
+    participant O as auth.openai.com
+    CLI->>CLI: PKCE verifier + S256 challenge, random state
+    CLI->>CLI: listen on 127.0.0.1:1455 (fallback 1457)
+    CLI->>B: open /oauth/authorize?client_id=…&code_challenge=…&state=…
+    B->>O: sign in to ChatGPT and approve
+    O-->>B: 302 → http://localhost:1455/auth/callback?code=…&state=…
+    B->>CLI: GET /auth/callback
+    CLI->>O: POST /oauth/token (authorization_code + code_verifier)
+    O-->>CLI: id_token, access_token, refresh_token
+    CLI->>CLI: write auth.json (0600, atomic), revoke the previous sign-in
+    CLI-->>B: 302 → /success ("You're signed in")
+    CLI-->>U: ✓ Signed in as you@example.com (ChatGPT plus plan)
+```
+
+1. **PKCE and state.** The CLI generates a PKCE pair (64 random bytes as a base64url verifier, plus its S256 challenge) and a random `state`.
+2. **Loopback server.** It starts a server on `127.0.0.1:1455`, falling back to `1457`. These exact ports are required: OpenAI allow-lists only `http://localhost:1455/auth/callback` and `…:1457/…` for this client. If a stale Codex or codex-imagegen login server holds the port, it is asked to `GET /cancel`, as Codex does.
+3. **Authorize URL.** It opens this URL in your browser:
+
+   ```text
+   https://auth.openai.com/oauth/authorize?response_type=code&client_id=app_EMoamEEZ73f0CkXaXp7hrann
+     &redirect_uri=http://localhost:1455/auth/callback&scope=openid%20profile%20email%20offline_access
+     &code_challenge=…&code_challenge_method=S256&id_token_add_organizations=true
+     &codex_cli_simplified_flow=true&state=…&originator=codex-imagegen-mcp
+   ```
+
+4. **Callback.** You sign in and approve, and the browser returns to `/auth/callback?code=…&state=…`.
+   - A mismatched `state` is answered with HTTP 400, and the login keeps waiting.
+   - An `error` parameter ends the login with a readable message. `missing_codex_entitlement` means Codex isn't enabled for the workspace.
+5. **Token exchange.** The code is exchanged for tokens at `POST https://auth.openai.com/oauth/token`, form-encoded with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id` and `code_verifier`.
+6. **Save.** The tokens are saved and the browser shows *You're signed in*. If this tool already had a sign-in, its refresh token is revoked.
+
+The flow times out after 10 minutes, and Ctrl+C cancels it. The `sign_in` MCP tool runs the same flow inside the server: it returns the link to the agent immediately, tries to open it, and finishes in the background.
+
+> [!NOTE]
+> **Scopes:** `openid profile email offline_access`. Codex also asks for `api.connectors.read api.connectors.invoke`, but the image endpoints don't need them, so this server asks for less.
+>
+> **Remote machines:** the redirect goes to `localhost`, so the browser must run on the same machine as the server. Over SSH, use the device code, or forward the port with `ssh -L 1455:localhost:1455 host` and open the printed URL locally.
+
+## Device-code sign-in
+
+```bash
+codex-imagegen-mcp login --device
+```
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as You (any device)
+    participant CLI as codex-imagegen-mcp
+    participant O as auth.openai.com
+    CLI->>O: POST /api/accounts/deviceauth/usercode {client_id}
+    O-->>CLI: device_auth_id, user_code, interval
+    CLI-->>U: open auth.openai.com/codex/device and enter ABCD-12345
+    loop every interval, for up to 15 minutes
+        CLI->>O: POST /api/accounts/deviceauth/token
+        O-->>CLI: 403 or 404 while approval is pending
+    end
+    U->>O: sign in and enter the code
+    O-->>CLI: authorization_code + code_verifier
+    CLI->>O: POST /oauth/token (redirect_uri = …/deviceauth/callback)
+    O-->>CLI: tokens
+```
+
+1. **Request a code.** `POST https://auth.openai.com/api/accounts/deviceauth/usercode` with `{client_id}` returns `{device_auth_id, user_code, interval}`.
+2. **Enter it.** You open **https://auth.openai.com/codex/device** on any device and enter the code, which is valid for 15 minutes.
+3. **Poll.** The CLI polls `POST …/api/accounts/deviceauth/token` with `{device_auth_id, user_code}`. HTTP 403 or 404 means approval is still pending.
+4. **Exchange.** Once you approve, the response carries `{authorization_code, code_verifier}`; the server supplies the PKCE pair. The code is exchanged at `/oauth/token` with `redirect_uri=https://auth.openai.com/deviceauth/callback`.
+
+> [!WARNING]
+> A 404 on step 1 means device codes are disabled for your account. Enable "device code authorization for Codex" in **ChatGPT → Settings → Security**. On a workspace, an admin may need to allow it.
+
+## Token storage
+
+The server's own `auth.json` is written atomically (temp file, then rename) with mode `0600`, in a `0700` directory:
+
+```json
+{
+  "version": 1,
+  "auth_mode": "chatgpt",
+  "tokens": {
+    "id_token": "<JWT>",
+    "access_token": "<JWT, ~10 day lifetime>",
+    "refresh_token": "<opaque, single-use>",
+    "account_id": "<chatgpt_account_id from the id_token>"
+  },
+  "last_refresh": "2026-09-23T01:02:03.000Z",
+  "login_method": "browser",
+  "created_at": "2026-09-23T01:02:03.000Z"
+}
+```
+
+The field names inside `tokens` match Codex's `auth.json`. Tokens are never logged; the log file records events only.
+
+## Refresh
+
+**When it happens:**
+- when the access token's `exp` is within **5 minutes**, as in Codex;
+- once `last_refresh` is 8 days old, if the token has no `exp`;
+- once after any **401** from the backend.
+
+**The request:** `POST https://auth.openai.com/oauth/token` with the JSON body `{"client_id": "…", "grant_type": "refresh_token", "refresh_token": "…"}`. There is no `scope`, exactly like Codex.
+
+**Concurrency.** MCP clients may run several server processes at once; opencode, for example, runs one per open project. Refreshes are therefore serialized:
+
+```mermaid
+sequenceDiagram
+    participant P1 as server process 1
+    participant L as auth.lock + auth.json
+    participant P2 as server process 2
+    participant O as auth.openai.com
+    P1->>L: take the lock
+    P2->>L: take the lock (waits)
+    P1->>L: re-read auth.json: still the stale token
+    P1->>O: refresh with refresh token R1
+    O-->>P1: access token A2 + refresh token R2 (R1 is now spent)
+    P1->>L: write A2/R2 atomically, release the lock
+    P2->>L: lock acquired, re-read auth.json: already rotated to A2
+    Note over P2: adopts A2 and never spends R1 a second time
+```
+
+Tests verify that three concurrent processes produce exactly one refresh call.
+
+**When a refresh fails:**
+- **Permanent:** `refresh_token_expired`, `refresh_token_reused`, `refresh_token_invalidated`, any 401, and 400 `invalid_grant`. You're asked to sign in again.
+- **Transient:** anything else. The current token is kept while it's still valid, and the refresh is retried on the next use.
+
+## Request headers
+
+| Header | Value |
+|---|---|
+| `Authorization` | `Bearer <access_token>` |
+| `ChatGPT-Account-ID` | `tokens.account_id`, the workspace to bill |
+| `originator` | `codex-imagegen-mcp` (override with `CODEX_IMAGEGEN_ORIGINATOR`) |
+| `User-Agent` | `codex-imagegen-mcp/<version> (<os> <release>; <arch>) node/<version>` |
+| `X-OpenAI-Fedramp` | `true`, only when the token's `chatgpt_account_is_fedramp` claim is true |
+
+## Plans and workspaces
+
+- **Plan:** read from the JWT claim `chatgpt_plan_type`. The Codex client hides image generation on **Free**. This server still sends the request and reports the backend's answer clearly.
+- **Workspace:** the sign-in's `chatgpt_account_id` claim. To use another workspace, sign in again and choose it on the consent screen; `sign_in` with `force: true` does this from the agent.
+- **Quota:** usage counts against your plan's Codex limits. `status` and `auth_status` read `GET https://chatgpt.com/backend-api/wham/usage`, which costs nothing, to show the 5-hour and weekly windows.
+
+## Signing out
+
+```bash
+codex-imagegen-mcp logout              # revoke the refresh token at /oauth/revoke, then delete auth.json
+codex-imagegen-mcp logout --no-revoke
+```
+
+Borrowed Codex and opencode sign-ins are never touched; sign out of those apps separately.
+
+## Troubleshooting
+
+| Message | Cause | Fix |
+|---|---|---|
+| `Not signed in to ChatGPT … (Checked — …)` | No source has a valid token | `login`, or open Codex/opencode once so their sign-in refreshes |
+| `…refresh token was already used` | Another machine or process spent the same refresh token (e.g. a copied `auth.json`) | `login` again, and don't share `auth.json` between machines |
+| `ports 1455 and 1457 are busy` | Another Codex or opencode login is waiting | Finish or close it, or use `--device` |
+| `Device-code sign-in is not enabled for this account` | Device codes are disabled | Enable them in ChatGPT → Settings → Security, or use the browser flow |
+| `Codex is not enabled for your ChatGPT workspace` | Workspace policy (`missing_codex_entitlement`) | Ask the workspace admin |
+| `ChatGPT rejected the … (HTTP 401)` | The token was revoked or expired on the server | `login` again |
+| `Access denied (HTTP 403)` | The plan or workspace lacks Codex image generation (e.g. Free) | Upgrade, or switch workspace |
+| `blocked by Cloudflare` | Your network was flagged | Retry later or from another network |
+
+## Security notes
+
+- **The OAuth client:** `app_EMoamEEZ73f0CkXaXp7hrann` is OpenAI's public native client for the Codex CLI. It has no client secret, and PKCE protects the flow. opencode's ChatGPT sign-in uses the same client. This project identifies itself honestly through `originator` and `User-Agent`.
+- **Your tokens:** they grant access to your ChatGPT account's Codex features. Treat `auth.json` like a password; that's why it's `0600`.
+- **What leaves your machine:** only requests to `auth.openai.com` and `chatgpt.com`, plus downloads of any `http(s)` input image URLs you pass. There is no telemetry.
+- **Terms of use:** this is an unofficial integration of an internal API. Use it within OpenAI's Terms of Use.
+
+---
+
+<p align="center"><a href="TOOLS.md">← Tools</a> &nbsp;·&nbsp; <a href="README.md">Docs home</a> &nbsp;·&nbsp; <a href="CLIENTS.md">Clients →</a></p>

package/docs/BACKEND.md

@@ -0,0 +1,169 @@
+<p align="center">
+  <img src="assets/banner-backend.jpg" width="100%" alt="Backend — a travel-poster illustration of a monumental concrete dam and powerhouse in a canyon, with transmission towers marching away toward a sun rising behind a peak">
+</p>
+
+# Backend
+
+How the image generation in OpenAI Codex really works. These findings come from taking apart the Codex desktop app and its bundled CLI, reading the matching open-source code, and measuring the live service. Nothing here is guessed; unmeasured points are marked as such.
+
+> [!NOTE]
+> **Measured on** 2026-09-22 and 2026-09-23 with a ChatGPT **Plus** account.
+> - **App:** Codex desktop `/Applications/ChatGPT.app`, bundle `com.openai.codex`, version 26.917.51856.
+> - **CLI:** its bundled `Contents/Resources/codex`, version 0.155.0-alpha.16.
+> - **Source:** `openai/codex@rust-v0.155.0-alpha.16`.
+
+**On this page:** [Two layers](#two-layers-a-skill-and-a-built-in-tool) · [The HTTP API](#the-http-api) · [What the service honors](#what-the-service-honors) · [Newer image models](#newer-image-models) · [Quota and rate limits](#quota-and-rate-limits) · [Output files](#output-files) · [Compared with Codex](#compared-with-codexs-built-in-tool)
+
+## Two layers: a skill and a built-in tool
+
+```mermaid
+flowchart LR
+    subgraph codex ["Codex app / CLI"]
+        skill["imagegen skill<br/>SKILL.md: when and how to prompt"]:::ochre
+        tool["built-in tool<br/>image_gen.imagegen"]:::rust
+        model["the model"]:::ink
+    end
+    backend["chatgpt.com/backend-api/codex<br/>/images/generations · /images/edits"]:::teal
+    file[("$CODEX_HOME/generated_images/<br/>thread/call_id.png")]:::cream
+    skill -. "read on demand" .-> model
+    model -- "prompt, reference images" --> tool
+    tool -- "Bearer token + ChatGPT-Account-ID" --> backend
+    backend -- "base64 PNG" --> tool
+    tool --> file
+    classDef ink fill:#2A2523,stroke:#9A8C76,color:#E4D9C6
+    classDef rust fill:#A6553B,stroke:#7E3F2B,color:#FFFFFF
+    classDef ochre fill:#D9A05B,stroke:#B5813F,color:#2A2523
+    classDef teal fill:#4E6E63,stroke:#3A544B,color:#FFFFFF
+    classDef cream fill:#E4D9C6,stroke:#A89A80,color:#2A2523
+    style codex fill:#D9A05B1F,stroke:#B5813F,color:#B5813F
+```
+
+1. **The `imagegen` skill** is instructions only.
+   - It's embedded in the `codex` binary and written to `$CODEX_HOME/skills/.system/imagegen/` on startup, fingerprinted in `.codex-system-skills.marker`.
+   - The model sees only its name, description and path, and reads `SKILL.md` on demand.
+   - It covers when to generate, how to structure prompts, and where to save.
+   - It also offers an API-key CLI fallback (`scripts/image_gen.py`) and a chroma-key helper (`scripts/remove_chroma_key.py`).
+   - A byte-exact copy is in [`upstream/codex-imagegen-skill/`](../upstream/codex-imagegen-skill/).
+2. **The built-in tool `image_gen.imagegen`** does the work.
+   - It's registered by the `codex-rs/ext/image-generation` crate as a namespaced function tool with three inputs: `prompt`, `referenced_image_paths` (up to 5 absolute paths) and `num_last_images_to_include` (1–5 recent images). The last two are mutually exclusive.
+   - It's offered only when **all** of these hold (`core/src/tools/spec_plan.rs`):
+     - the `image_generation` feature is on, which it is by default;
+     - the account is **not on Free**;
+     - the model accepts image input;
+     - the provider uses ChatGPT auth. API-key auth gets no tool.
+
+## The HTTP API
+
+```http
+POST https://chatgpt.com/backend-api/codex/images/generations    # no input images
+POST https://chatgpt.com/backend-api/codex/images/edits          # with input images
+Authorization: Bearer <ChatGPT OAuth access token>
+ChatGPT-Account-ID: <chatgpt_account_id>
+originator: <client id, e.g. codex_cli_rs>
+User-Agent: <originator>/<version> (<os>; <arch>) <terminal>
+Content-Type: application/json
+
+{"prompt":"…","background":"auto","model":"gpt-image-2","quality":"auto","size":"auto"}
+# edits add: "images":[{"image_url":"data:image/png;base64,…"}]  (max 5)
+```
+
+- **Constants:** Codex hard-codes `model: "gpt-image-2"`, `quality: "auto"`, `size: "auto"` and `background: "auto"` (`ext/image-generation/src/tool.rs`). Upstream `main` was unchanged as of 2026-09-22.
+- **Response:**
+  - Body: `{created, background, data:[{b64_json, generation_id}], output_format, quality, size, usage}`.
+  - Headers: `x-codex-imagegen-request-id`, `x-oai-request-id`, and the rate-limit headers below.
+- **What Codex does with it:** it decodes the first image to `$CODEX_HOME/generated_images/<thread>/<call_id>.png` and returns it to the model with a note that the user can already see it. The desktop app renders it inline, with Edit/Canvas actions.
+
+## What the service honors
+
+| Request | Result |
+|---|---|
+| `size: "17x17"` | 1536×1024; an invalid size is silently ignored |
+| `size: "1024x1024"`, `quality: "medium"`, `output_format: "jpeg"`, `n: 2` | **1370×1148, quality `low`, PNG, one image**: all four ignored |
+| `model: "gpt-image-bogus-does-not-exist"` | 200 OK and a normal image: the model is ignored |
+| `background: "transparent"` (generation) | **An RGBA PNG** with real alpha (opaque areas carry alpha 251–254) |
+| `background: "transparent"` (edit: "remove the table and backdrop") | **An RGBA PNG**, 55% fully transparent |
+| `background: "opaque"` plus a prompt about keying out a green backdrop | **A transparent PNG anyway**; rewording the green as printed paper returned an opaque image |
+| A prompt starting "Tall vertical 9:16 portrait phone wallpaper: …" | **941×1672**, exactly 9:16 |
+| A prompt ending "Aspect ratio: 16:9, wide landscape (horizontal) canvas." | **1672×941**, exactly 16:9 |
+| The same line with `21:9` / `1:1` | **1916×821** / **1254×1254** |
+| An edit with a 21:9 reference image and a `21:9` line | **1916×821**; style carried over, the new composition followed the prompt |
+| 4 requests in parallel on one account | All returned 200, in 17–25 s each |
+
+> [!IMPORTANT]
+> **Only `prompt`, `background` and `images` influence the result**, and even `background` is a strong hint rather than a switch. Model, quality, pixel size, count and format are chosen by the service. The canvas shape follows the **prompt text**.
+
+That's why this server:
+- exposes `aspect_ratio` as a prompt line;
+- implements `n` as parallel requests;
+- converts JPEG output locally;
+- verifies the alpha channel on every transparent request;
+- offers no `model`, `size` or `quality` parameter that would be silently ignored.
+
+## Newer image models
+
+OpenAI released `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare` on 2026-09-08. On the public Images API they add `xhigh`/`max` quality and native transparency. Through a **ChatGPT sign-in**:
+
+- **The images endpoint** (`/backend-api/codex/images/*`) ignores the model name. Requests for a 2.5 model, `xhigh`/`max` quality or a 2K size came back at the service's default size, with `medium` or `low` quality.
+- **The Responses endpoint** (`POST /backend-api/codex/responses` with the hosted `image_generation` tool) **rewrites the tool config** to `{"model":"gpt-image-2-codex","quality":"auto","size":"auto",…}`, as its `response.created` echo shows. Options the rewritten model doesn't support are rejected up front:
+
+  | Option | Error |
+  |---|---|
+  | `background: "transparent"` | `400 image_generation_user_error: "Transparent background is not supported for this model."` |
+  | `input_fidelity` | `400 invalid_input_fidelity_model: "The model 'gpt-image-2-codex' does not support the 'input_fidelity' parameter."` |
+  | An unknown model name | fails with `server_is_overloaded` |
+
+  This path also returns a `revised_prompt`, but it adds a chat-model turn, so it's slower and costlier.
+- **The Codex app's "ImageGen 2.5" announcement** ("Image creation got a major upgrade") is gated by a Statsig flag. The client still sends `gpt-image-2`, so the upgrade happens on the server: whatever model backs `gpt-image-2` for Codex (reported as `gpt-image-2-codex`) is what every ChatGPT-signed-in client gets.
+
+> [!TIP]
+> A ChatGPT sign-in can't select a model. This server, like Codex, automatically gets OpenAI's server-side upgrades to the Codex image model. Picking `gpt-image-2.5-*` explicitly, with exact sizes or `xhigh`/`max` quality, requires the billed OpenAI Platform API, which is out of scope by design.
+
+## Quota and rate limits
+
+**`GET https://chatgpt.com/backend-api/wham/usage`** takes the same auth headers and costs **no quota**. It returns:
+- `plan_type`;
+- `rate_limit.{allowed, limit_reached, primary_window, secondary_window}`, where the primary window is 5 hours (`limit_window_seconds: 18000`) and the secondary is weekly (`604800`), each with `used_percent`, `reset_at` and `reset_after_seconds`;
+- `additional_rate_limits` and `credits`.
+
+The Codex apps use it for their usage display, and this server uses it for `auth_status`, `status` and `doctor`.
+
+Every image response also carries headers:
+
+| Header | Meaning |
+|---|---|
+| `x-codex-plan-type` | The plan, e.g. `plus` |
+| `x-codex-active-limit` | The limit being counted (observed: `premium`) |
+| `x-codex-{primary,secondary}-{used-percent,window-minutes,reset-at,reset-after-seconds}` | Window state |
+| `x-codex-credits-*` | Credits balance and flags |
+| `x-image-gen-*` | A separate image limit (limit id `image_gen`), when one applies |
+
+- **Exhausted limits:** a `429` returns `{"error":{"type":"usage_limit_reached","resets_at":…,"plan_type":…}}`, and `usage_not_included` means the plan lacks the feature.
+- **Retries:** Codex retries 5xx and transport errors, never 429. So does this server.
+- **Cost of a session:** generating the 15 images for these docs used about 5% of a Plus plan's 5-hour window and 1% of the weekly one.
+
+## Output files
+
+- **Format and size:** PNG at about 1.5 MP, shaped by the prompt: 1536×1024, 1024×1536, 1672×941, 941×1672, 1916×821, 1254×1254 or 1370×1148.
+- **Latency:** 12–48 s per request.
+- **Provenance:** every file carries a **C2PA** manifest in a `caBX` chunk. It's signed by "OpenAI Media Service", with claim generator `ChatGPT`/`gpt-image` and `digitalSourceType` `trainedAlgorithmicMedia`. This server writes the service's PNG bytes unchanged, so the manifest survives; converting to JPEG drops it.
+
+## Compared with Codex's built-in tool
+
+| | Codex built-in `image_gen` | codex-imagegen-mcp |
+|---|---|---|
+| **Clients** | Codex CLI, IDE and app only | Any MCP client |
+| **Auth** | Codex's ChatGPT sign-in | Its own sign-in (browser or device), or Codex/opencode borrowed read-only |
+| **Endpoint and body** | `/images/{generations,edits}`, as above | Identical |
+| **Save location** | `$CODEX_HOME/generated_images/…`; the model copies files into the project | Directly to `output_path` in the workspace, never overwriting, or the library |
+| **Inputs** | Absolute paths or recent images | Paths (workspace-relative works), URLs, data URLs |
+| **Aspect ratio** | Via the prompt | The `aspect_ratio` parameter, written as a prompt line |
+| **Variants** | One call per variant | `n` from 1 to 4, in parallel |
+| **Transparency** | `background` not exposed ("ask for transparency") | `background: "transparent"` passed through, and the alpha verified |
+| **Chroma key** | A Python script | The built-in `remove_background` tool, same algorithm |
+| **Result for the model** | The full image | A 1024 px JPEG preview, with the full file on disk |
+
+Authentication is covered in [Authentication](AUTH.md): OAuth (PKCE or device code) with the Codex public client, roughly 10-day access tokens and rotating single-use refresh tokens. The minimal scopes (`openid profile email offline_access`) are enough for the image endpoints.
+
+---
+
+<p align="center"><a href="CLIENTS.md">← Clients</a> &nbsp;·&nbsp; <a href="README.md">Docs home</a> &nbsp;·&nbsp; <a href="ARCHITECTURE.md">Architecture →</a></p>

package/docs/CLIENTS.md

@@ -0,0 +1,154 @@
+<p align="center">
+  <img src="assets/banner-clients.jpg" width="100%" alt="Clients — a travel-poster illustration of a desert railway junction where several tracks converge on one small station with a water tower">
+</p>
+
+# Clients
+
+The server is a local **stdio** MCP server, so any MCP client can run it: many tracks, one station. opencode installs with one command, and every other client takes a short snippet that `codex-imagegen-mcp config <client>` prints for you.
+
+**On this page:** [Support matrix](#support-matrix) · [opencode](#opencode-automated) · [Claude Code](#claude-code) · [OpenAI Codex](#openai-codex-cli-and-ide) · [Claude Desktop](#claude-desktop) · [Cursor](#cursor) · [VS Code](#vs-code-github-copilot-agent-mode) · [Windsurf](#windsurf) · [Gemini CLI](#gemini-cli) · [Any other client](#any-other-client)
+
+## Support matrix
+
+| Client | Setup | Tools appear as |
+|---|---|---|
+| **opencode** | `install opencode`: writes `opencode.json[c]` and the skill (automated) | `imagegen_generate_image` |
+| **Claude Code** | `claude mcp add …`, skill in `~/.claude/skills/` | `mcp__imagegen__generate_image` |
+| **OpenAI Codex** | `config codex` → `~/.codex/config.toml` | `mcp__imagegen__generate_image` |
+| **Claude Desktop** | `config claude-desktop` → `claude_desktop_config.json` | listed under `imagegen` |
+| **Cursor** | `config cursor` → `~/.cursor/mcp.json` | listed under `imagegen` |
+| **VS Code** (Copilot agent mode) | `config vscode` → `.vscode/mcp.json` | listed under `imagegen` |
+| **Windsurf** | `config windsurf` → `~/.codeium/windsurf/mcp_config.json` | listed under `imagegen` |
+| **Gemini CLI** | `config gemini` → `~/.gemini/settings.json` | listed under `imagegen` |
+
+Every client needs two things:
+
+1. **The launch command.** After the [one-line install](../README.md#quick-start) (or `npm link` from a checkout) it's `codex-imagegen-mcp serve`; straight from a checkout it's `node /path/to/codex-imagegen-mcp/dist/src/cli.js serve`. `codex-imagegen-mcp config <client>` prints the exact snippet for your machine, with absolute paths where a GUI app needs them.
+2. **Optionally, the Agent Skill** in `skill/imagegen/`. It teaches the agent the prompting and save-path workflow. Clients without skill support can read the same content from the server as `imagegen://skill/SKILL.md`, and the essentials are also in the server's MCP instructions.
+
+Then sign in once with `codex-imagegen-mcp login`, unless Codex or opencode is already signed in with ChatGPT. See [Authentication](AUTH.md).
+
+## opencode (automated)
+
+```bash
+codex-imagegen-mcp install opencode              # global: ~/.config/opencode/opencode.json[c] + skills/imagegen
+codex-imagegen-mcp install opencode --project    # this project only: ./opencode.json + .opencode/skills/imagegen
+codex-imagegen-mcp install opencode --dry-run    # show what would change
+codex-imagegen-mcp uninstall opencode            # remove the entry and the skill it installed
+```
+
+The installer adds this entry, editing with `jsonc-parser` so comments, formatting and your other servers stay exactly as they were:
+
+```jsonc
+"mcp": {
+  "imagegen": {
+    "type": "local",
+    "command": ["node", "/…/dist/src/cli.js", "serve"],
+    "enabled": true,
+    "timeout": 300000
+  }
+}
+```
+
+> [!NOTE]
+> opencode applies `timeout` to **every** MCP request, tool calls included, and resets it on each progress notification. 300 s is a safe ceiling.
+
+What the installer does, and what it refuses to do:
+
+- **Backs up first.** The previous config is saved to `opencode.json.codex-imagegen-mcp.bak`.
+- **Won't clobber a stranger.** If another server already uses the name, it refuses unless you pass `--force`; `--name` picks a different name.
+- **Owns only what it installed.** The skill is copied to `~/.config/opencode/skills/imagegen` with a marker file, so `uninstall` removes only a copy it created.
+- **Warns about duplicates.** opencode resolves duplicate skill names unpredictably, so the installer warns if another `imagegen` skill exists anywhere opencode looks: `~/.claude/skills`, `~/.agents/skills`, `~/.config/opencode/skill[s]`, `~/.opencode/skill[s]` and the project equivalents.
+
+```bash
+opencode mcp list                    # ✓ imagegen connected
+opencode run "Make a 16:9 hero image of a lighthouse at dusk and save it to assets/hero.png"
+```
+
+- **Where files land:** opencode starts the server in the project directory and reports it as an MCP root, so relative `output_path`s land in the project.
+- **Previews reach vision models on every provider.** With OpenAI models over ChatGPT, previews travel inside the tool result. GitHub Copilot and other providers receive them as a follow-up attachment. Both paths are verified with `openai/gpt-5.5` and `github-copilot/claude-sonnet-5`.
+- **Options:** `--env KEY=VALUE` (repeatable) sets environment variables, for example `--env CODEX_IMAGEGEN_OUTPUT_DIR=~/Pictures/ai`. `--command "…"` overrides the launch command.
+
+## Claude Code
+
+```bash
+claude mcp add --scope user imagegen -- node /path/to/codex-imagegen-mcp/dist/src/cli.js serve
+mkdir -p ~/.claude/skills && cp -R /path/to/codex-imagegen-mcp/skill/imagegen ~/.claude/skills/
+```
+
+- Tools appear as `mcp__imagegen__generate_image`, and so on.
+- Generation takes 15–60 s. If you hit tool timeouts, start Claude Code with `MCP_TOOL_TIMEOUT=300000`.
+
+> [!WARNING]
+> opencode also reads `~/.claude/skills`. If you install the skill for both, keep only **one** copy, or keep the copies identical.
+
+## Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "imagegen": { "command": "/opt/homebrew/bin/node", "args": ["/path/to/codex-imagegen-mcp/dist/src/cli.js", "serve"] }
+  }
+}
+```
+
+- **Use absolute paths.** GUI apps don't inherit your shell `PATH`; `codex-imagegen-mcp config claude-desktop` prints the right ones.
+- **Pass absolute `output_path`s.** Claude Desktop starts servers with `/` as the working directory. Without an `output_path`, images go to the image library.
+
+## Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{ "mcpServers": { "imagegen": { "command": "node", "args": ["/path/to/codex-imagegen-mcp/dist/src/cli.js", "serve"] } } }
+```
+
+## VS Code (GitHub Copilot agent mode)
+
+Add to `.vscode/mcp.json`, or run **MCP: Open User Configuration**:
+
+```json
+{ "servers": { "imagegen": { "type": "stdio", "command": "node", "args": ["/path/to/codex-imagegen-mcp/dist/src/cli.js", "serve"] } } }
+```
+
+## Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{ "mcpServers": { "imagegen": { "command": "/opt/homebrew/bin/node", "args": ["/path/to/codex-imagegen-mcp/dist/src/cli.js", "serve"] } } }
+```
+
+## Gemini CLI
+
+Add to `~/.gemini/settings.json`:
+
+```json
+{ "mcpServers": { "imagegen": { "command": "node", "args": ["/path/to/codex-imagegen-mcp/dist/src/cli.js", "serve"], "timeout": 300000 } } }
+```
+
+## OpenAI Codex (CLI and IDE)
+
+When Codex is signed in with ChatGPT, it already has this capability built in (`image_gen`), so this entry is mainly useful for API-key Codex setups. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.imagegen]
+command = "node"
+args = ["/path/to/codex-imagegen-mcp/dist/src/cli.js", "serve"]
+tool_timeout_sec = 300
+```
+
+## Any other client
+
+Any MCP client that can launch a stdio server works: point it at `codex-imagegen-mcp serve`. For the best experience the client should:
+
+- allow tool calls of at least about 90 s, or reset its timeout on progress notifications;
+- support image content in tool results, so the model sees the preview. Without it, the model still gets the saved paths and metadata.
+
+Skills: Claude Code reads `~/.claude/skills/`; clients that follow the Agent Skills convention read `~/.agents/skills/`; opencode reads the directories listed above.
+
+---
+
+<p align="center"><a href="AUTH.md">← Authentication</a> &nbsp;·&nbsp; <a href="README.md">Docs home</a> &nbsp;·&nbsp; <a href="BACKEND.md">Backend →</a></p>