codex-pet

What this skill does

# Codex Pet — Pro Pack on RunComfy

[runcomfy.com](https://www.runcomfy.com/?utm_source=skills.sh&utm_medium=skill&utm_campaign=codex-pet) · [GPT Image 2 edit endpoint](https://www.runcomfy.com/models/openai/gpt-image-2/edit?utm_source=skills.sh&utm_medium=skill&utm_campaign=codex-pet) · [docs](https://docs.runcomfy.com/cli/introduction?utm_source=skills.sh&utm_medium=skill&utm_campaign=codex-pet)

**Codex Pet generator on RunComfy.** Turn one source image into a Codex-compatible custom Codex Pet — `pet.json` + `spritesheet.webp` — drop it into `${CODEX_HOME:-$HOME/.codex}/pets/<name>/`, Codex picks it up next to the 8 built-in Codex Pets.

```bash
npx skills add agentspace-so/runcomfy-agent-skills --skill codex-pet -g
```

## What a Codex Pet is

OpenAI Codex Pets (released May 2026) are pixel-art animated companions that float over your desktop while Codex codes — they react to mouse interaction and Codex status (scratching head when thinking, popping a speech bubble when a task completes). Codex ships with 8 built-in Codex Pets and supports custom Codex Pets installed locally as a folder under `${CODEX_HOME:-$HOME/.codex}/pets/`.

Each custom Codex Pet folder contains exactly two files:

- `pet.json` — manifest with `id`, `displayName`, `description`, `spritesheetPath`.
- `spritesheet.webp` — Codex Pet sprite atlas, **1536x1872** PNG or WebP, 8 columns x 9 rows of 192x208 cells, transparent background.

The 9 rows correspond to 9 animation states Codex plays. Each row uses a fixed number of leading frames; trailing cells stay fully transparent.

## Why this Codex Pet skill (vs OpenAI's official `hatch-pet`)

OpenAI ships an official [`hatch-pet`](https://github.com/openai/skills/blob/main/skills/.curated/hatch-pet/SKILL.md) skill that produces the same Codex Pet artifact via the Codex-internal `$imagegen` system skill (requires Codex Pro + `$imagegen` configured).

**This Codex Pet skill is a drop-in alternative that runs via the RunComfy CLI**: a single `RUNCOMFY_TOKEN` plus `runcomfy` and `magick` binaries — no Codex Pro, no `$imagegen`, no OPENAI_API_KEY. The output Codex Pet artifact is identical — same `pet.json` shape, same `spritesheet.webp` 1536x1872 atlas, same 9 animation rows — so Codex treats this Codex Pet exactly like one made by `hatch-pet`.

This skill follows the same pattern Codex's built-in Codex Pets use: **one canonical pose, replicated across cells with ImageMagick micro-transforms** for subtle animation (1-2 px shifts, blink frames, tilt frames). That matches what the official `hatch-pet` output actually looks like cell-by-cell — the Codex Pet animation visible in the Codex desktop app is intentionally subtle.

Pick this skill when:

- You want a custom Codex Pet but don't have Codex Pro / `$imagegen`.
- You want a custom Codex Pet built via the RunComfy Model API.
- You want **batch Codex Pet generation** from a folder of source images (one canonical call per pet).
- You're entering the OpenAI Codex Pet contest with a different model behind the visuals.
- You said "codex pet", "/hatch", "make me a codex pet", "spritesheet.webp", "desktop pet for codex" explicitly.

## Codex Pet animation rows

Codex reads one fixed atlas: 8 columns, 9 rows, 192x208 cells. Each Codex Pet row corresponds to one animation state with a specific number of leading frames.

| Row | State | Used columns | Frames | Codex Pet behavior |
|---|---|---|---|---|
| 0 | idle | 0-5 | 6 | calm breathing/blinking; the reduced-motion first frame for the Codex Pet |
| 1 | running-right | 0-7 | 8 | Codex Pet locomotion to the right |
| 2 | running-left | 0-7 | 8 | mirrored locomotion to the left |
| 3 | waving | 0-3 | 4 | greeting / attention gesture |
| 4 | jumping | 0-4 | 5 | anticipation, lift, peak, descent, settle |
| 5 | failed | 0-7 | 8 | error / sad / deflated reaction |
| 6 | waiting | 0-5 | 6 | patient idle variant |
| 7 | running | 0-5 | 6 | active working / in-progress loop (NOT foot-running) |
| 8 | review | 0-5 | 6 | focused / inspecting / thinking |

Trailing cells after each row's last used column must be fully transparent.

## Codex Pet style

The Codex Pet visual house style:

- **EXAGGERATED chibi proportions**: head occupies ~60 percent of total figure height; body and legs are tiny stubby and short. The whole figure should fit a near-square bounding box.
- pixel-art-adjacent low-resolution mascot, chunky silhouette
- thick dark 1-2 px outlines, visible stepped pixel edges
- limited palette, flat cel shading, simple expressive face, tiny limbs
- transparent background

Avoid: motion lines, drop shadows, glows, sparkles, floating effects, text labels, scenery, white/black backgrounds.

## Prerequisites

1. **RunComfy CLI** — `npm i -g @runcomfy/cli`
2. **RunComfy account** — `runcomfy login`. CI alternative: `RUNCOMFY_TOKEN=<token>`.
3. **ImageMagick** — `brew install imagemagick` (macOS) or `apt-get install imagemagick` (Linux). Provides the `magick` command for the deterministic atlas assembly.
4. **A source image URL** — publicly fetchable HTTPS, JPEG/PNG/WebP, the subject the Codex Pet will be modeled on.

## Codex Pet pipeline (1 GPT Image 2 call, ~2 min)

1. **Canonical Codex Pet** — single `runcomfy run openai/gpt-image-2/edit` call producing one 1024x1024 chibi pose on a magenta chroma-key background.
2. **Cell normalization** — chroma-key magenta → alpha 0, trim, aspect-fit into 192x208 with transparent padding.
3. **9 row strips, programmatic** — for each of 9 animation states, build the row's 8 cells via ImageMagick micro-transforms (translate / mask / mirror) of the canonical cell. Trailing cells filled with transparent 192x208.
4. **Atlas** — stack 9 row strips vertically into the 1536x1872 Codex Pet atlas.
5. **WebP** — convert atlas PNG to WebP.
6. **Manifest + install** — write `pet.json`, copy both files into `${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/`.

The micro-transform approach matches what Codex's built-in Codex Pets actually do — the Codex Pet animation is intentionally subtle, so 1-2 px shifts and blink masks per cell give the right visual feel without burning 72 GPT Image 2 calls.

### Step 1: Generate the canonical Codex Pet (1 call)

```bash
PET_NAME="my-pet"
PET_DESC="A friendly companion for late-night refactors."
SOURCE_URL="https://.../source.png"
RUN_DIR="./codex-pet-run/${PET_NAME}"
CHROMA="#FF00FF"   # magenta chroma-key
mkdir -p "${RUN_DIR}"

runcomfy run openai/gpt-image-2/edit \
  --input "{
    \"prompt\": \"Generate one canonical Codex digital pet sprite based on the input image. EXAGGERATED chibi proportions: the head occupies about 60 percent of the total figure height; body and legs are tiny stubby and short. The whole pet figure must fit within a near-square bounding box (overall aspect close to 1:1). Pixel-art-adjacent low-resolution mascot, chunky whole-body silhouette, thick dark 1-2 px outline, visible stepped pixel edges, limited palette, flat cel shading, simple expressive face, tiny limbs. Centered in the image. No polished illustration, no painterly render, no anime key art, no 3D render, no glossy app-icon polish, no realistic detail. Background: solid flat magenta ${CHROMA} chroma-key fill outside the pet silhouette. The pet itself must not use the chroma-key color or any close-to-magenta highlights. No gradients, no shadows, no halos, no scenery, no text. Identity preserved from the input image.\",
    \"images\": [\"${SOURCE_URL}\"],
    \"size\": \"1024*1024\"
  }" \
  --output-dir "${RUN_DIR}/decoded/"

BASE=$(ls "${RUN_DIR}/decoded/"*.png | head -1)
echo "canonical Codex Pet: ${BASE}"
```

### Step 2: Normalize the canonical into a 192x208 Codex Pet cell

Chroma-key magenta to alpha, trim to the pet sprite bounding box, aspect-fit into 192x208 with transparent padding.

```bash
magick "${BASE}" \
  -fuzz 18% -transparent "${CHROMA}" \
  -alpha set \
  -trim +repage \
  -resize 192x208 \
  -gravity center \
  -background none \
  -extent 192x208 \
  "${RUN_DIR}/cell.png"
```

The