@heart-of-gold/toolkit 0.1.45 → 0.1.46

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@heart-of-gold/toolkit",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "type": "module",
-  "description": "Cross-platform installer for Heart of Gold skills — works with Codex, OpenCode, Pi, Claude Code, and more",
+  "description": "Cross-platform installer for Heart of Gold skills \u2014 works with Codex, OpenCode, Pi, Claude Code, and more",
   "bin": {
     "heart-of-gold": "src/index.ts"
   },

package/plugins/babel-fish/skills/image/SKILL.md

@@ -2,7 +2,7 @@
 name: image
 description: >
   AI image generation and editing. Text-to-image, style transfer, and logo generation.
-  Currently powered by Gemini and FLUX via OpenRouter.
+  Powered by GPT Image 2 (via Codex CLI, no API key), Gemini, and FLUX.
   Triggers: generate image, create image, make image, draw, illustrate, logo, visual, picture.
 allowed-tools:
   - Read
@@ -26,10 +26,23 @@ Translating your thoughts into pictures. The Babel Fish handles all languages, i
 
 | Backend | When to Use | Key |
 |---------|-------------|-----|
-| Gemini (`gemini-3-pro-image-preview`) | Primary — best quality, text in images, style transfer | `GEMINI_API_KEY` |
-| FLUX via OpenRouter (`black-forest-labs/flux.2-pro`) | Fallback — artistic, creative work | `~/.claude/secrets/openrouter.json` |
+| GPT Image 2 via Codex CLI (`gpt-image-2`) | Default — strong prompt adherence, text in images, no API key | ChatGPT OAuth (`codex login`) |
+| Gemini (`gemini-3-pro-image-preview`) | Style transfer with reference images, multi-turn iteration, 4K | `GEMINI_API_KEY` |
+| FLUX via OpenRouter (`black-forest-labs/flux.2-pro`) | Artistic, stylised work | `~/.claude/secrets/openrouter.json` |
 
-Check `$GEMINI_API_KEY` first; if unset, fall back to `~/.claude/secrets/openrouter.json`.
+## Backend selection (ask first)
+
+Before generating, ask via `AskUserQuestion` which backend to use — list the three above as options with GPT Image 2 first (default). Skip the question only when:
+
+- The user already named a backend in their prompt ("use Gemini", "with FLUX", "via codex")
+- The request **forces** a specific one:
+  - Reference images for style matching → Gemini (the codex path does not accept reference images)
+  - True native transparent background → Gemini, or codex with explicit `gpt-image-1.5`
+  - 4K+ output above 3840px per edge → Gemini (codex caps at 3840)
+
+Announce the chosen backend in one line before running so the user has clarity.
+
+Requires: `codex-cli >= 0.124.0-alpha.2` for GPT Image 2. Install: `npm install -g @openai/codex@0.124.0-alpha.2`.
 
 ## Phase 0 — Understand
 
@@ -43,7 +56,31 @@ Gather before generating. Ask if unclear:
 
 ## Phase 1 — Generate
 
-### Gemini (primary)
+### GPT Image 2 via Codex (default)
+
+Runs through codex's built-in `image_gen` tool — uses your ChatGPT OAuth, no API key, no per-image billing (counts against your ChatGPT plan limits).
+
+```bash
+plugins/babel-fish/skills/image/scripts/generate_image_codex.sh \
+  --output ./output.png \
+  --size 1024x1024 \
+  --quality high \
+  "your prompt here"
+```
+
+Constraints:
+- Sizes: `auto` or `WxH` — max edge ≤ 3840px, edges multiples of 16, 655k–8.3M total pixels.
+- Quality: `low` | `medium` | `high` | `auto`.
+- Does **not** support `background=transparent` — use Gemini or ask codex for `gpt-image-1.5` explicitly if true transparency is required.
+
+Equivalent raw invocation (skip the wrapper for multi-variant riffs):
+
+```bash
+codex exec --skip-git-repo-check --sandbox workspace-write --full-auto \
+  "Use your built-in image_gen tool to generate: <PROMPT>. After it returns, copy the file to <OUT_PATH> and print the path."
+```
+
+### Gemini
 
 ```python
 import os
@@ -74,7 +111,7 @@ for part in response.parts:
 
 **Critical:** Gemini returns JPEG by default. Use `.jpg` extension. If PNG is needed, pass `format="PNG"` explicitly to `img.save()`.
 
-### FLUX via OpenRouter (fallback)
+### FLUX via OpenRouter
 
 ```bash
 curl https://openrouter.ai/api/v1/images/generations \

package/plugins/babel-fish/skills/image/scripts/generate_image_codex.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Generate an image via Codex CLI's built-in image_gen tool (gpt-image-2).
+# Uses ChatGPT OAuth — no OPENAI_API_KEY required.
+# Requires: codex-cli >= 0.124.0-alpha.2
+
+set -euo pipefail
+
+PROMPT=""
+OUTPUT="./generated_image.png"
+SIZE=""
+QUALITY=""
+
+usage() {
+  cat <<'EOF'
+Usage: generate_image_codex.sh [options] "prompt"
+
+Options:
+  -o, --output PATH    Output file (default: ./generated_image.png)
+  --size SIZE          e.g. 1024x1024, 1536x1024, 3840x2160, or auto
+  --quality LEVEL      low | medium | high | auto
+  -h, --help           Show this help
+
+Examples:
+  generate_image_codex.sh "a red apple on a white table"
+  generate_image_codex.sh --output logo.png --quality high "a minimalist fox logo"
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -o|--output)   OUTPUT="$2"; shift 2 ;;
+    --size)        SIZE="$2"; shift 2 ;;
+    --quality)     QUALITY="$2"; shift 2 ;;
+    -h|--help)     usage; exit 0 ;;
+    --)            shift; PROMPT="${1:-}"; shift || true ;;
+    -*)            echo "Unknown flag: $1" >&2; usage >&2; exit 2 ;;
+    *)             PROMPT="$1"; shift ;;
+  esac
+done
+
+if [[ -z "$PROMPT" ]]; then
+  echo "Error: prompt is required" >&2
+  usage >&2
+  exit 2
+fi
+
+if ! command -v codex >/dev/null 2>&1; then
+  echo "Error: codex CLI not found on PATH." >&2
+  echo "Install: npm install -g @openai/codex@0.124.0-alpha.2" >&2
+  exit 1
+fi
+
+OUT_DIR="$(cd "$(dirname "$OUTPUT")" 2>/dev/null && pwd || echo "$(pwd)")"
+OUT_ABS="$OUT_DIR/$(basename "$OUTPUT")"
+mkdir -p "$OUT_DIR"
+
+INSTR="Use your built-in image_gen tool to generate a single image: $PROMPT"
+[[ -n "$SIZE" ]]    && INSTR+=$'\nSize: '"$SIZE"
+[[ -n "$QUALITY" ]] && INSTR+=$'\nQuality: '"$QUALITY"
+INSTR+=$'\nAfter image_gen returns, copy the generated file to '"$OUT_ABS"$' and print that absolute path as the final line. Do not use the fallback CLI scripts/image_gen.py.'
+
+echo "Generating via codex built-in image_gen (gpt-image-2)..." >&2
+echo "Prompt: $PROMPT" >&2
+
+codex exec \
+  --skip-git-repo-check \
+  --sandbox workspace-write \
+  --full-auto \
+  -C "$OUT_DIR" \
+  "$INSTR" 2>/dev/null | tail -3
+
+if [[ -f "$OUT_ABS" ]]; then
+  echo "Image saved to: $OUT_ABS"
+else
+  echo "Error: expected image at $OUT_ABS but none was written." >&2
+  exit 1
+fi

package/plugins/guide/skills/codex/SKILL.md

@@ -75,3 +75,18 @@ Codex is powered by OpenAI models with their own knowledge cutoffs and limitatio
 - Stop and report failures whenever `codex --version` or a `codex exec` command exits non-zero; request direction before retrying.
 - Before using high-impact flags (`--full-auto`, `--sandbox danger-full-access`, `--skip-git-repo-check`) ask the user for permission using `AskUserQuestion` unless already given.
 - When output includes warnings or partial results, summarize them and ask how to adjust using `AskUserQuestion`.
+
+## Image Generation (codex ≥ 0.124.0-alpha.2)
+
+Codex ships a built-in `image_gen` tool that uses OpenAI's `gpt-image-2` under the user's ChatGPT OAuth — **no `OPENAI_API_KEY` required**. To invoke it:
+
+```bash
+codex exec --skip-git-repo-check --sandbox workspace-write --full-auto \
+  "Use your built-in image_gen tool to generate: <PROMPT>. After it returns, copy the file to <OUT_PATH> and print the path."
+```
+
+- Supported models (server-picked): `gpt-image-2` (default, newest), `gpt-image-1.5` (only one supporting `background=transparent`), `gpt-image-1`, `gpt-image-1-mini`.
+- Quality: `low` | `medium` | `high` | `auto`. Sizes: `auto` or `WxH` with max edge ≤ 3840px, edges multiples of 16, 655k–8.3M total pixels.
+- Output lands in `$CODEX_HOME/generated_images/<session>/<hash>.png` — ask the agent to copy to the user's target.
+- Convenience wrapper (handles prompt assembly + output copy) is at `~/.claude/skills/image-gen/scripts/generate_image_codex.sh`; the `image-gen` skill documents the full UX. Prefer that wrapper over hand-rolling the codex invocation.
+- Do **not** use codex's bundled fallback script `scripts/image_gen.py` — it requires an `OPENAI_API_KEY`, which is precisely what the built-in path avoids.