name: imagine description: Generate images through Oracle's ChatGPT browser automation. Use when the user asks to create, imagine, draw, generate, or download AI images with ChatGPT image mode, especially when they mention Oracle, imagine, generated images, Create image mode, or saving image outputs from ChatGPT.

Imagine

Use Oracle's browser-backed imagine tool to generate ChatGPT images and save the resulting files. This workflow relies on the user's existing ChatGPT browser cookies through Oracle; do not use API keys and do not use manual-login flows.

ChatGPT Intelligence Setting

Image generation must run with ChatGPT's Intelligence pill set to Instant. This is intentional and different from non-image Oracle consults, which should use Pro Extended / browserThinkingTime: "extended".

Critical rules:

Example MCP shape:

mcp__oracle__imagine({
  prompt: "Create one image: <image prompt>. No text, no captions.",
  files: ["/abs/path/reference.png"],
  slug: "image-proof-run"
})

Expected proof in output.log:

Thinking time: Instant
[browser] [image] Create image mode enabled

Long-Running Expectations

ChatGPT image generation through Oracle is a blocking browser workflow. After Codex starts an Oracle imagine run, all local output decisions and follow-up work MUST pause until Oracle fully completes and the saved/generated outputs have been inspected.

Workflow

  1. Prefer the Oracle MCP imagine tool when it is available.

    • Pass the user's image request as prompt.
    • Use files only when the user provides reference images or assets.
    • Set a descriptive slug when supported.
    • Use browserKeepBrowser only when debugging.
    • Wait until Oracle completes; elapsed time alone never permits continuing without the Oracle result.
  2. If the MCP surface is unavailable, use the Oracle CLI or project-local script that exposes the same imagine tool rather than rebuilding browser automation by hand.

    • Keep the run in browser/cookie mode.
    • Do not provide OPENAI_API_KEY.
    • Do not use --manual-login.
    • If remote oracle serve is configured, prefer it when it is the established path for ChatGPT cookies.
  3. Verify outputs at the file level.

    • Confirm the run reports generated image captures.
    • Save returned image payloads to a clear output directory.
    • Run file <images> or equivalent to verify real PNG/JPEG/WebP image data.
    • Report the exact output directory and count.
    • If a short tool wait expires, check the Oracle session/output directory and keep waiting until Oracle completes or reports a terminal failure before deciding no images were produced.
  4. Be honest about ChatGPT batch limits.

    • If the user asks for N images and ChatGPT returns fewer, report the actual count.
    • Run a follow-up image generation for the remaining count when the user clearly asked for an exact number.

Batches: request the full batch, adapt the size

When the user wants N images, request them in one imagine call as a batch, not as N separate calls. Batch prompts must be insanely clear:

The tool result often returns fewer images than requested — this is almost always capture timing, not the model refusing (see the recovery workflow below). Handle it like this:

ChatGPT fulfills the full requested count (verified up to 6 images per call, both distinct scenes and variations). Historically the Oracle harness captured too early — it harvested ~1.5s after the FIRST image finished, silently dropping the rest of every batch. Fixed 2026-06-10 in tv:~/dev/oracle/src/browser/actions/generatedImages.ts: waitForNewGeneratedImage now waits for a 20s render-quiet window (no element-count changes, no stop-button/incomplete-image indicators) before capture, and captures whatever completed instead of throwing on deadline. A batch-of-5 call now returns 5/5.

Batch workflow:

  1. Request all N images in one call (numbered distinct scenes or "Generate N variations of this image" — both fulfill).
  2. Compare requested vs captured. If ever short again, check the session's output.log: "detected X new generated image element(s)" much greater than "captured M" means renders were still in flight at capture.
  3. Recovery fallback (verified repeatedly): take the conversation URL from output.log ("conversation url (post-response)"), wait a few minutes, then call imagine again with browserConversationUrl set to that URL and a text-only prompt such as "Do not generate or create any images in this response. Reply with only the digit count of images above." The capture pass collects ALL completed images in the conversation; checksum (md5 -q) against already-saved files to identify the new ones. This also recovers shortfalls from any pre-fix session.

Long runs: queue file + spacing

For sets larger than a handful of images, space imagine calls ~5 minutes apart to avoid quota exhaustion, and drive the run from a checklist queue file instead of conversation memory:

Character consistency (reference images)

To keep the same person across a multi-scene set, pass a previous generated image via files on every call. Verified to hold across 18 scenes and 3 different protagonists with this prompt shape:

Failure modes and session paths

Prompting

Always forbid text when the user did not request typography. Batch skeleton:

Create exactly N separate images. Each is its own standalone image file.
Image 1: <complete scene description>.
Image 2: <complete scene description>.
...
Output all N as N separate images. No text, no captions, no typography.

Guardrail / Content-Policy Refusals

ChatGPT may refuse an image prompt with text like:

The imagine MCP tool detects these refusals and returns isError: true with structuredContent.status === "guardrail" and the verbatim ChatGPT message in structuredContent.guardrailMessage. Treat this as a prompt problem, not a tool failure:

Completion Criteria

Finish only after one of these is true:

Never finish while an Oracle image generation is still processing.

In the final response, include the saved path, number of verified images, and any mismatch between requested and generated counts.

---
name: imagine
description: Generate images through Oracle's ChatGPT browser automation. Use when the user asks to create, imagine, draw, generate, or download AI images with ChatGPT image mode, especially when they mention Oracle, imagine, generated images, Create image mode, or saving image outputs from ChatGPT.
---

# Imagine

Use Oracle's browser-backed `imagine` tool to generate ChatGPT images and save the resulting files. This workflow relies on the user's existing ChatGPT browser cookies through Oracle; do not use API keys and do not use manual-login flows.

## ChatGPT Intelligence Setting

Image generation must run with ChatGPT's Intelligence pill set to **Instant**.
This is intentional and different from non-image Oracle consults, which should
use **Pro Extended** / `browserThinkingTime: "extended"`.

Critical rules:

- For ChatGPT image generation, use Instant every time. Image mode does not need
  Pro Extended, and Pro Extended can slow or stall image runs.
- If using `mcp__oracle__imagine`, the current Oracle tool/server should enforce
  Instant automatically for Create image mode. Do not override it to extended.
- If using the CLI recovery path, pass the image/Create-image equivalent of
  `--browser-thinking-time instant` when the CLI exposes that flag.
- Verify the run log when debugging: `~/.oracle/sessions/{slug}/output.log`
  should include `Thinking time: Instant` before or near `Create image mode enabled`.
- Do not apply this Instant rule to text-only Oracle research, code review, or
  planning. Those non-image ChatGPT consults should stay on Pro Extended.

Example MCP shape:

```text
mcp__oracle__imagine({
  prompt: "Create one image: <image prompt>. No text, no captions.",
  files: ["/abs/path/reference.png"],
  slug: "image-proof-run"
})
```

Expected proof in `output.log`:

```text
Thinking time: Instant
[browser] [image] Create image mode enabled
```

## Long-Running Expectations

ChatGPT image generation through Oracle is a blocking browser workflow. After Codex starts an Oracle `imagine` run, all local output decisions and follow-up work MUST pause until Oracle fully completes and the saved/generated outputs have been inspected.

- Never assume Oracle timed out or failed based on elapsed time alone.
- Never proceed independently while Oracle is still processing, even if a wrapper returns after 120s or any other local wait limit.
- Do not report "Oracle timed out at 120s" as a final failure. Reattach/check session state or inspect saved outputs until Oracle completes or reports a terminal failure.
- Do not retry immediately just because no image was returned after 120 seconds; duplicate retries can create extra generations and confuse output counts.
- If using the CLI Oracle recovery path, run it in browser/cookie mode and wait for completion, or reattach to the Oracle session and inspect `~/.oracle/sessions/<slug>/`.
- Keep waiting as long as Oracle requires while the session is still processing. There is no Codex-side timeout threshold that permits independent action.
- Only treat the run as failed when Oracle reports an explicit error, the browser is blocked, the session exits non-zero, or the logs show ChatGPT refused/failed to generate.

## Workflow

1. Prefer the Oracle MCP `imagine` tool when it is available.
   - Pass the user's image request as `prompt`.
   - Use `files` only when the user provides reference images or assets.
   - Set a descriptive `slug` when supported.
   - Use `browserKeepBrowser` only when debugging.
   - Wait until Oracle completes; elapsed time alone never permits continuing without the Oracle result.

2. If the MCP surface is unavailable, use the Oracle CLI or project-local script that exposes the same `imagine` tool rather than rebuilding browser automation by hand.
   - Keep the run in browser/cookie mode.
   - Do not provide `OPENAI_API_KEY`.
   - Do not use `--manual-login`.
   - If remote `oracle serve` is configured, prefer it when it is the established path for ChatGPT cookies.

3. Verify outputs at the file level.
   - Confirm the run reports generated image captures.
   - Save returned image payloads to a clear output directory.
   - Run `file <images>` or equivalent to verify real PNG/JPEG/WebP image data.
   - Report the exact output directory and count.
   - If a short tool wait expires, check the Oracle session/output directory and keep waiting until Oracle completes or reports a terminal failure before deciding no images were produced.

4. Be honest about ChatGPT batch limits.
   - If the user asks for N images and ChatGPT returns fewer, report the actual count.
   - Run a follow-up image generation for the remaining count when the user clearly asked for an exact number.

## Batches: request the full batch, adapt the size

When the user wants N images, request them **in one `imagine` call as a batch**, not as N separate calls. Batch prompts must be insanely clear:

- Open with the exact count: "Create exactly 10 separate images. Each is its own standalone image file, not panels of one image."
- Number every scene ("Image 1: …", "Image 2: …") and give each a complete, self-contained description — never "same as above but…".
- Close by restating the count: "Output all 10 as 10 separate images."

The tool result often returns fewer images than requested — this is almost always capture timing, not the model refusing (see the recovery workflow below). Handle it like this:

- Count what actually came back, then **visually inspect each file to identify which numbered scene it is** — returned order is NOT guaranteed to match prompt order, so never name files by position alone.
- If fewer than requested came back, **run the conversation-revisit recovery first** (next section) before re-requesting anything — the missing images usually finished rendering after capture and are sitting in the conversation.
- Do NOT shrink the requested count in response to a shortfall — controlled experiments showed lowering the batch size never changed what ChatGPT produced, only what the early capture happened to catch.
- Run calls sequentially, not in parallel — Oracle drives a single browser session.

ChatGPT fulfills the full requested count (verified up to 6 images per call, both distinct scenes and variations). Historically the Oracle harness captured too early — it harvested ~1.5s after the FIRST image finished, silently dropping the rest of every batch. **Fixed 2026-06-10** in `tv:~/dev/oracle/src/browser/actions/generatedImages.ts`: `waitForNewGeneratedImage` now waits for a 20s render-quiet window (no element-count changes, no stop-button/incomplete-image indicators) before capture, and captures whatever completed instead of throwing on deadline. A batch-of-5 call now returns 5/5.

Batch workflow:

1. Request all N images in one call (numbered distinct scenes or "Generate N variations of this image" — both fulfill).
2. Compare requested vs captured. If ever short again, check the session's `output.log`: "detected X new generated image element(s)" much greater than "captured M" means renders were still in flight at capture.
3. **Recovery fallback (verified repeatedly):** take the conversation URL from `output.log` ("conversation url (post-response)"), wait a few minutes, then call `imagine` again with `browserConversationUrl` set to that URL and a text-only prompt such as "Do not generate or create any images in this response. Reply with only the digit count of images above." The capture pass collects ALL completed images in the conversation; checksum (`md5 -q`) against already-saved files to identify the new ones. This also recovers shortfalls from any pre-fix session.

## Long runs: queue file + spacing

For sets larger than a handful of images, space `imagine` calls ~5 minutes apart to avoid quota exhaustion, and drive the run from a checklist queue file instead of conversation memory:

- Write a markdown queue listing every scene as `- [ ] <id> \`<name>\` — <full self-contained scene description>`, plus the per-call workflow (slug pattern, output dir, reference image path if any).
- Schedule a recurring ~5-minute job whose prompt says "take the first unchecked item, generate it, verify, copy, mark `[x]`"; record the job ID in the queue file and have the final iteration delete the job and report.
- Log each iteration's requested/received counts in the queue file so batch-size adaptation survives across iterations.

## Character consistency (reference images)

To keep the same person across a multi-scene set, pass a previous generated image via `files` on every call. Verified to hold across 18 scenes and 3 different protagonists with this prompt shape:

- Open with: "Use the uploaded photo as a character reference: the same person — <short physical description: age, hair, clothing> — must appear in this new image with a clearly recognizable identical face."
- Close with: "…same color grade and mood as the reference photo."
- Still generate one scene per call, and visually confirm the face matches before saving — re-describe the person in words every time; the upload alone is not enough.

## Failure modes and session paths

- `create-image-menu-item-not-found` (or similar pre-generation browser errors where the session fails before ChatGPT starts rendering): nothing was generated, so an immediate single retry is safe and does not risk duplicates. This is distinct from timeouts, where retrying can duplicate generations.
- Long slugs get truncated in the session ID (e.g. slug `terminal-love-story-04-anniversary` → session `terminal-love-story-04-anniversar`). Always take output locations from the returned `sessionId`/`imagePaths` in the tool result — never construct paths from the slug you passed.

## Prompting

Always forbid text when the user did not request typography. Batch skeleton:

```text
Create exactly N separate images. Each is its own standalone image file.
Image 1: <complete scene description>.
Image 2: <complete scene description>.
...
Output all N as N separate images. No text, no captions, no typography.
```

## Guardrail / Content-Policy Refusals

ChatGPT may refuse an image prompt with text like:

- "We're so sorry, but the prompt may violate our guardrails concerning similarity to third-party content. If you think we got it wrong, please retry or edit your prompt."
- "We're so sorry, but the image we created may violate our content policies. If you think we got it wrong, please retry or edit your prompt."

The `imagine` MCP tool detects these refusals and returns `isError: true` with `structuredContent.status === "guardrail"` and the verbatim ChatGPT message in `structuredContent.guardrailMessage`. Treat this as a **prompt problem, not a tool failure**:

- Do not retry the same prompt — it will be refused again.
- Tell the user the prompt likely hits a copyright / third-party-content boundary (named characters, trademarked styles, recognizable likenesses, etc.).
- Offer to rephrase: drop named IP, describe stylistic elements generically, or shift to an original concept.
- Only retry after the prompt has been edited.

## Completion Criteria

Finish only after one of these is true:

- The requested images are saved and verified as image files.
- The tool or ChatGPT failed in a way that cannot be recovered in the current turn, and the failure details are reported with the last useful log lines.

Never finish while an Oracle image generation is still processing.

In the final response, include the saved path, number of verified images, and any mismatch between requested and generated counts.