gabelul/pixeltamer-gpt-image-skill
pixeltamer
FlaggedGenerate, 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |