Skip to content

gabelul/pixeltamer-gpt-image-skill

pixeltamer

Flagged

Generate, edit, and compose images with GPT Image 2.6, including transparent PNGs with a real alpha channel. Three backends — OpenAI API key (full feature set), codex CLI on your ChatGPT subscription (agent-driven, no key needed), or the direct ChatGPT image route on the same subscription token (--backend codex-images, PNG-only, opt-in). Four modes — one-shot generate, edit or inpaint an existing image, multi-reference composition (up to 16 inputs blended into one), and multi-image batch with verification. Use when the user asks to make an image, generate a poster, draw a mockup, design an icon or sticker, create an ad creative, build an infographic, blend reference images, edit or inpaint an existing image, or produce a cutout asset with a transparent background — "transparent PNG", "no background", "alpha channel", "works on any background". Not for: stripping the background off an existing image you want to keep (that's rembg or ImageMagick, not a generator); file operations that don't change the picture (compression, format conversion, resizing); reading, describing or OCRing an image; video.

scripts/pixeltamer

View on GitHub
#!/usr/bin/env bash
# pixeltamer — image generation dispatcher.
#
# Picks a backend (OpenAI API or codex CLI), auto-detects from env, and dispatches
# to the right helper script. First time it runs without config, walks you through
# a quick interactive setup.
#
# Subcommands:
#   generate  text -> image (default if no subcommand given)
#   edit      modify or inpaint a single image (API only)
#   compose   blend 2-16 reference images into one (API only)
#   batch     plan + generate multiple images with verification (multi-image flow)
#   config    re-run interactive setup
#   doctor    diagnose your install
#
# Run `pixeltamer <subcommand> --help` for per-command flags.

set -euo pipefail

prog="$(basename "$0")"
script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/pixeltamer"
config_file="$config_dir/config.json"

# --- helpers ----------------------------------------------------------------

_log()  { printf "%s\n" "$*" >&2; }
_die()  { _log "$prog: $*"; exit 1; }
_have() { command -v "$1" >/dev/null 2>&1; }

_have_api_key() {
  [[ -n "${OPENAI_IMAGE_API_KEY:-}" ]] || [[ -n "${OPENAI_API_KEY:-}" ]]
}

_have_codex() {
  # Note: `codex login status` writes its "Logged in" message to stderr in
  # current versions, so we redirect stderr into stdout before piping to grep.
  # Using `2>/dev/null` here would silently hide the very string we grep for.
  _have codex && codex login status 2>&1 | grep -qi "logged in"
}

# Self-heal exec permissions on sibling scripts. The `skills` CLI's file copy
# strips +x mode bits when it places files into ~/.claude/skills/, ~/.codex/skills/,
# etc. — so a fresh `npx skills add` or `npx skills update` leaves every script
# non-executable.
#
# As of the bash-invoke change below, NO sibling strictly needs +x anymore: the
# Python/Node helpers are run via `python3`/`node` and pixeltamer_codex.sh is run
# via `bash`. This repair is now belt-and-suspenders — it protects any FUTURE
# sibling that gets direct-exec'd, and keeps `pixeltamer doctor` able to report
# the count. The one file we still can't fix from here is the dispatcher itself
# (it must already be +x for this code to run); that's an upstream skills-CLI bug
# — see README / docs/dev-docs/troubleshooting.md for the manual one-liner.
# Returns the count of files repaired; caller decides whether to surface it.
_self_heal_perms() {
  local fixed=0 candidate
  for candidate in \
    "$script_dir/pixeltamer_codex.sh" \
    "$script_dir/pixeltamer_api.py" \
    "$script_dir/pixeltamer_codex_oauth.py" \
    "$script_dir/verify-images.mjs"
  do
    if [[ -f "$candidate" && ! -x "$candidate" ]]; then
      chmod +x "$candidate" 2>/dev/null && fixed=$((fixed + 1))
    fi
  done
  echo "$fixed"
}

_load_config() {
  # Load saved backend preference, if any.
  if [[ -f "$config_file" ]] && _have python3; then
    PIXELTAMER_BACKEND_PREF="$(python3 -c "
import json, sys
try:
  print(json.load(open('$config_file')).get('backend', ''))
except Exception:
  pass
")"
  fi
  PIXELTAMER_BACKEND_PREF="${PIXELTAMER_BACKEND_PREF:-auto}"
}

_save_config() {
  local backend="$1"
  mkdir -p "$config_dir"
  if _have python3; then
    python3 -c "
import json, os
cfg = {}
p = '$config_file'
if os.path.exists(p):
  try:
    cfg = json.load(open(p))
  except Exception:
    cfg = {}
cfg['backend'] = '$backend'
json.dump(cfg, open(p, 'w'), indent=2)
"
  else
    printf '{ "backend": "%s" }\n' "$backend" >"$config_file"
  fi
  _log "saved → $config_file"
}

_detect_backend() {
  # Resolve which backend to use right now, honoring (in order):
  #   1. --backend flag (already in $BACKEND_OVERRIDE)
  #   2. PIXELTAMER_BACKEND env var
  #   3. saved config preference
  #   4. auto: api if key set, else codex if logged in
  local choice="${BACKEND_OVERRIDE:-${PIXELTAMER_BACKEND:-${PIXELTAMER_BACKEND_PREF:-auto}}}"
  case "$choice" in
    api|openai)
      _have_api_key || _die "backend=api but no OPENAI_IMAGE_API_KEY/OPENAI_API_KEY set"
      echo "api"
      ;;
    codex)
      _have_codex || _die "backend=codex but codex CLI not installed or not logged in"
      echo "codex"
      ;;
    codex-images)
      # Same OAuth pool as the codex backend, but the transport is the
      # ChatGPT-backend image route inside pixeltamer_api.py — no codex exec,
      # no orchestrator. Needs the codex login (for auth.json tokens).
      _have_codex || _die "backend=codex-images but codex CLI not installed or not logged in (its OAuth token is the transport's auth)"
      echo "codex-images"
      ;;
    auto|"")
      # codex-images is deliberately absent from auto: it is opt-in only —
      # PNG-only and size-blind, so silently picking it would silently
      # downgrade requests the default backends handle.
      if _have_api_key; then echo "api"
      elif _have_codex;   then echo "codex"
      else
        _die "no backend available. Run \`$prog config\` to set one up."
      fi
      ;;
    *)
      _die "unknown backend: $choice (expected api|codex|codex-images|auto)"
      ;;
  esac
}

# --- subcommands ------------------------------------------------------------

# Flags no codex transport can honour. Both hardcode PNG output, so asking for
# jpeg/webp there can only lie to you.
#
# `--background` is deliberately NOT in this list. Codex can't take it as a
# parameter — the OAuth Responses transport accepts the field in its schema and
# then rejects the value ("Transparent background is not supported for this
# model") — but codex's image_gen produces real alpha when the *prompt* asks for
# it. So every codex path translates the flag into prompt text and verifies the
# result, rather than refusing a capability that works: generate via
# pixeltamer_codex.sh; edit/compose via pixeltamer_codex_oauth.py, where
# prompt-driven transparency was measured working on 2026-11-06 (a codex edit
# came back with a real alpha channel — 62% transparent pixels, maxAlpha 255).
# opaque/auto remain codex-refused: the transport has no such control.

_die_if_api_only_flag() {
  local arg
  for arg in "$@"; do
    case "$arg" in
      --output-format|--output-format=*|--output-compression|--output-compression=*)
        _die "\`${arg%%=*}\` requires the API backend — both codex transports always return PNG. Set OPENAI_API_KEY, or pass --backend api."
        ;;
      --input-fidelity|--input-fidelity=*)
        _die "\`--input-fidelity\` requires the API backend — the codex Responses transport doesn't expose it. Set OPENAI_API_KEY, or pass --backend api."
        ;;
    esac
  done
}

cmd_generate() {
  local backend
  backend="$(_detect_backend)"
  case "$backend" in
    api)   exec python3 "$script_dir/pixeltamer_api.py" generate "$@" ;;
    # Invoke via `bash` (not direct exec) so a +x bit stripped by the skills CLI
    # copy can't break codex generation — matches how the py/node helpers run.
    codex)
      _die_if_api_only_flag "$@"
      exec bash "$script_dir/pixeltamer_codex.sh" "$@"
      ;;
    codex-images)
      # The API client handles route-specific rejections itself (png-only,
      # no size) with precise per-flag messages — so unlike the codex case,
      # --output-format png is welcome here and wrong formats fail closed.
      exec env PIXELTAMER_CODEX_IMAGES=1 python3 "$script_dir/pixeltamer_api.py" generate "$@"
      ;;
  esac
}

cmd_edit() {
  local backend
  backend="$(_detect_backend)"
  case "$backend" in
    api)
      exec python3 "$script_dir/pixeltamer_api.py" edit "$@"
      ;;
    codex)
      # Codex Responses API can edit, but it doesn't take a mask. If --mask
      # was passed, route through API instead with a clear-but-quiet handoff.
      local has_mask=0
      for arg in "$@"; do
        if [[ "$arg" == "--mask" || "$arg" == --mask=* ]]; then
          has_mask=1
          break
        fi
      done
      if (( has_mask == 1 )); then
        _die "\`edit --mask\` requires the API backend (codex Responses API doesn't take a mask parameter). Set OPENAI_API_KEY or pass --backend api."
      fi
      _die_if_api_only_flag "$@"
      # --background transparent now flows through: the oauth script turns it
      # into a prompt clause and alpha-verifies the result.
      exec python3 "$script_dir/pixeltamer_codex_oauth.py" edit "$@"
      ;;
    codex-images)
      # Mask/format/etc. rejections live in the API client's codex-images
      # validator — one place owns the route's capability matrix.
      exec env PIXELTAMER_CODEX_IMAGES=1 python3 "$script_dir/pixeltamer_api.py" edit "$@"
      ;;
  esac
}

cmd_compose() {
  local backend
  backend="$(_detect_backend)"
  case "$backend" in
    api)   exec python3 "$script_dir/pixeltamer_api.py" compose "$@" ;;
    codex)
      _die_if_api_only_flag "$@"
      # See cmd_edit: --background transparent is prompt-driven + verified.
      exec python3 "$script_dir/pixeltamer_codex_oauth.py" compose "$@"
      ;;
    codex-images)
      exec env PIXELTAMER_CODEX_IMAGES=1 python3 "$script_dir/pixeltamer_api.py" compose "$@"
      ;;
  esac
}

cmd_batch() {
  # An image-producing entry point must never answer a --json request with
  # prose. Batch has its own state machine and no envelope yet, so it refuses
  # in the contract's own shape rather than ignoring the flag.
  for arg in "$@"; do
    if [[ "$arg" == "--json" ]]; then
      printf '{"schema_version":1,"ok":false,"command":"batch","error":{"code":"unsupported_on_backend","message":"batch has no --json envelope yet; it writes status back into prompts.md instead","retryable":"no"}}\n'
      exit 1
    fi
  done

  # Multi-image state-machine flow. Delegates to verify-images.mjs which
  # parses prompts.md, calls the right backend per entry, and verifies output.
  if ! _have node; then
    _die "\`batch\` needs Node.js 18+. Install from https://nodejs.org"
  fi
  exec node "$script_dir/verify-images.mjs" "$@"
}

cmd_config() {
  cat <<EOF >&2
$prog setup
==========
Pick how pixeltamer should generate images.

  [1] OpenAI API key       (fastest, full features, costs per image)
  [2] Codex CLI            (uses your ChatGPT subscription, no key required)
  [3] Codex subscription   (direct ChatGPT image route; PNG only, no size control)
  [4] Auto-detect          (try API first, fall back to codex)  [recommended]
  [5] Cancel
EOF
  printf "your pick [4]: " >&2
  read -r choice
  case "${choice:-4}" in
    1) _save_config api ;;
    2) _save_config codex ;;
    3) _save_config codex-images ;;
    4) _save_config auto ;;
    5) _log "cancelled."; exit 0 ;;
    *) _die "invalid choice: $choice" ;;
  esac

  echo >&2
  echo "Current backend status:" >&2
  if _have_api_key; then echo "  api    ✓ key present"; else echo "  api    ✗ set OPENAI_API_KEY"; fi >&2
  if _have_codex;   then echo "  codex  ✓ codex installed and logged in"; else echo "  codex  ✗ run: codex login"; fi >&2
  if _have_codex;   then echo "  codex-images ✓ opt-in: --backend codex-images (uses codex OAuth)"; else echo "  codex-images ✗ needs codex login"; fi >&2
}

# Read the skill version straight out of package.json. sed-only so it works
# even when python3/node aren't installed (doctor is exactly when they might
# not be). package.json carries "version" once, so grabbing the first match
# is safe.
_pixeltamer_version() {
  local pkg="$script_dir/../package.json"
  [[ -f "$pkg" ]] || { echo "unknown"; return; }
  local v
  v="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$pkg" | head -n1)"
  echo "${v:-unknown}"
}

# Latest pixeltamer release version from GitHub. pixeltamer isn't on npm — it's a
# Skills-CLI skill — so the latest published version is the newest GitHub release
# tag. Owner/repo is parsed out of package.json's repository.url so it's not
# hardcoded. Network call bounded by curl --max-time; returns empty (and doctor
# skips the staleness line) when curl is missing, offline, or rate-limited.
_latest_skill_version() {
  command -v curl >/dev/null 2>&1 || return 0
  local pkg="$script_dir/../package.json" url repo
  [[ -f "$pkg" ]] || return 0
  url="$(sed -n 's/.*"url"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$pkg" | head -1)"
  repo="$(printf '%s' "$url" | sed -E 's#.*github\.com[/:]##; s#\.git$##; s#/$##')"
  [[ -n "$repo" ]] || return 0
  curl -fsSL --max-time 6 "https://api.github.com/repos/$repo/releases/latest" 2>/dev/null \
    | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"v\{0,1\}\([^"]*\)".*/\1/p' | head -1
}

# Installed codex version, e.g. "codex-cli 0.138.0" -> 0.138.0.
_codex_installed_version() { codex --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1; }

# Latest version of an npm package. Network call, bounded by a perl alarm so a
# slow or offline registry can never hang doctor — it just comes back empty and
# we skip the staleness line. perl is guaranteed on macOS; macOS has no
# coreutils `timeout`, which is why we don't use it here.
_npm_latest() {
  command -v npm >/dev/null 2>&1 || return 0
  perl -e 'alarm 6; exec @ARGV' npm view "$1" version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1
}

cmd_doctor() {
  echo "$prog doctor"
  echo "=============="
  echo
  # Skill version + staleness. "Latest" is the newest GitHub release; if the
  # installed skill is behind, the fix is `npx skills update` (which the docs
  # note also needs the one-line dispatcher chmod afterward).
  local sv lsv
  sv="$(_pixeltamer_version)"
  lsv="$(_latest_skill_version)"
  if [[ -z "$lsv" || "$sv" == "unknown" ]]; then
    echo "pixeltamer:         v$sv"
  elif [[ "$sv" == "$lsv" ]]; then
    echo "pixeltamer:         v$sv  (latest)"
  elif [[ "$(printf '%s\n%s\n' "$sv" "$lsv" | sort -V | tail -1)" == "$lsv" ]]; then
    echo "pixeltamer:         v$sv  → update available: v$lsv"
    echo "                    run: npx skills update   (then chmod +x the dispatcher — see README)"
  else
    echo "pixeltamer:         v$sv  (ahead of latest release v$lsv)"
  fi
  echo
  # Self-heal exec bits on siblings first — most "doctor reports codex/api as
  # missing" reports trace back to a non-executable helper that the dispatcher
  # silently couldn't invoke.
  local healed
  healed="$(_self_heal_perms)"
  if [[ "$healed" -gt 0 ]]; then
    echo "perms self-heal:    fixed +x on $healed script(s) in $script_dir"
    echo "                    (the skills CLI installer strips mode bits on copy)"
    echo
  fi
  # Check the dispatcher's own +x — we can only get here if it's executable,
  # but report it so users can copy/paste a one-liner if they hit the issue
  # on a sibling install path (project-level vs user-level skill dirs).
  if [[ ! -x "$script_dir/pixeltamer" ]]; then
    echo "dispatcher +x:      MISSING — run: chmod +x $script_dir/pixeltamer"
    echo
  fi
  echo "config file:        $config_file"
  if [[ -f "$config_file" ]]; then
    echo "config exists:      yes"
    [[ -r "$config_file" ]] && cat "$config_file" | sed 's/^/  /'
  else
    echo "config exists:      no  (run: $prog config)"
  fi
  echo
  echo "backend availability:"
  if _have_api_key; then
    echo "  api    ✓ OPENAI_*_KEY set"
  else
    echo "  api    ✗ no OPENAI_IMAGE_API_KEY or OPENAI_API_KEY"
  fi
  if _have codex; then
    if codex login status 2>&1 | grep -qi "logged in"; then
      echo "  codex  ✓ installed and logged in"
    else
      echo "  codex  ⚠ installed but not logged in (run: codex login)"
    fi
  else
    echo "  codex  ✗ not installed (npm install -g @openai/codex)"
  fi
  if _have_codex; then
    echo "  codex-images ✓ opt-in: --backend codex-images (ChatGPT image route on codex OAuth; PNG only)"
  else
    echo "  codex-images ✗ needs codex login"
  fi
  echo
  echo "runtime versions:"
  echo "  python3: $(python3 --version 2>&1 || echo 'missing')"
  echo "  node:    $(node --version 2>&1 || echo 'missing')"
  echo "  bash:    $BASH_VERSION"

  # codex CLI version + staleness. A stale codex is a real failure mode for this
  # skill — the v0.136/gpt-5.5 schema mismatch caused indefinite hangs — and
  # `npx skills update` does NOT touch it (codex is installed separately). The
  # latest-check is network-bounded and skips silently when offline.
  if _have codex; then
    local cv lv
    cv="$(_codex_installed_version)"
    lv="$(_npm_latest @openai/codex)"
    if [[ -z "$cv" ]]; then
      echo "  codex:   installed (version unreadable)"
    elif [[ -z "$lv" ]]; then
      echo "  codex:   $cv  (couldn't reach npm to check for updates)"
    elif [[ "$cv" == "$lv" ]]; then
      echo "  codex:   $cv  (latest)"
    elif [[ "$(printf '%s\n%s\n' "$cv" "$lv" | sort -V | tail -1)" == "$lv" ]]; then
      echo "  codex:   $cv  → update available: $lv"
      echo "           run: npm install -g @openai/codex@latest   (skill update does NOT update codex)"
    else
      echo "  codex:   $cv  (ahead of npm latest $lv)"
    fi
  fi
}

usage() {
  cat <<EOF
$prog — image generation for Claude Code, Codex CLI, OpenCode, and friends.

usage:
  $prog [--backend api|codex|codex-images|auto] <subcommand> [args...]
  # --backend is accepted before or after the subcommand

subcommands:
  generate (default)   text -> image
  edit                 modify a single image (mask requires API; OAuth path otherwise)
  compose              blend 2-16 reference images into one (API or codex-OAuth)
  batch                plan + generate multiple images with verification
  config               interactive setup
  doctor               diagnose install

shortcuts:
  $prog "make me a poster of X"     # = generate -p "..."
  $prog -p "X" -o image.png         # = generate

env:
  OPENAI_API_KEY / OPENAI_IMAGE_API_KEY     OpenAI API auth
  PIXELTAMER_BACKEND                         api | codex | codex-images | auto
  OPENAI_IMAGE_BASE_URL                      override API base URL
  OPENAI_IMAGE_MODEL                         override API model (default gpt-image-2.6-flare)

backends:
  api           full feature surface (needs OPENAI_API_KEY)
  codex         codex CLI agent; PNG only, GIFs assembled by the agent
  codex-images  direct ChatGPT image route on codex OAuth; PNG only, no size control

run \`$prog <subcommand> --help\` for per-command flags.
EOF
}

# --- main -------------------------------------------------------------------

# Pull --backend off wherever it appears before dispatch. The helpers never
# accept the flag themselves — leaving it in the tail used to make them
# reject it, which only worked when the flag happened to sit in front of the
# subcommand. Placement no longer matters.
BACKEND_OVERRIDE=""
args=()
while [[ $# -gt 0 ]]; do
  if [[ "$1" == "--backend" ]]; then
    BACKEND_OVERRIDE="${2:-}"
    shift 2
  elif [[ "$1" == --backend=* ]]; then
    BACKEND_OVERRIDE="${1#--backend=}"
    shift
  else
    args+=("$1")
    shift
  fi
done
# The ${args[@]+...} guard keeps an empty array legal under bash 3.2 with `set -u`.
if [[ ${#args[@]} -gt 0 ]]; then set -- ${args[@]+"${args[@]}"}; else set --; fi

_load_config

# Silent self-heal of sibling script +x bits. The `skills` CLI installer copies
# files without preserving POSIX mode, so a fresh install leaves api/codex/oauth
# helpers non-executable. We've already proven we can run (the dispatcher is +x),
# so quietly fix siblings before any subcommand tries to exec them.
# Skip when subcommand is `doctor` — doctor does its own loud self-heal pass and
# we don't want to silently consume the signal it needs to report.
if [[ "${1:-}" != "doctor" && "${1:-}" != "diagnose" ]]; then
  _self_heal_perms >/dev/null 2>&1 || true
fi

# First-run nudge: if no config and no backend obviously available, prompt setup.
if [[ ! -f "$config_file" ]] && ! _have_api_key && ! _have_codex; then
  if [[ -t 0 && -t 1 ]]; then
    _log "$prog: no backend configured and no creds detected — running setup..."
    _log ""
    cmd_config
    _log ""
  fi
fi

# Dispatch
case "${1:-}" in
  ""|-h|--help|help)
    usage
    ;;
  generate|gen)
    shift
    cmd_generate "$@"
    ;;
  edit)
    shift
    cmd_edit "$@"
    ;;
  compose)
    shift
    cmd_compose "$@"
    ;;
  batch)
    shift
    cmd_batch "$@"
    ;;
  config|setup)
    shift
    cmd_config "$@"
    ;;
  doctor|diagnose)
    shift
    cmd_doctor "$@"
    ;;
  -p|--prompt|-i|--image|-o|--out|--size|--quality|-n|--style|--background|--output-format|--output-compression|--input-fidelity|--json|--format|--moderation|--user|--concurrency|--model|--mask|--complexity|--frames|--frame-ms)
    # Bare flags = implicit `generate`.
    cmd_generate "$@"
    ;;
  *)
    # Free-text first arg = treat as a generate prompt: `pixeltamer "make me X"`
    if [[ "$1" != -* ]]; then
      cmd_generate -p "$1" "${@:2}"
    else
      _die "unknown subcommand: $1 (try: $prog --help)"
    fi
    ;;
esac
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall