Back to Details

codex-pet

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codex Pet — Pro Pack on RunComfy

RunComfy上的Codex Pet专业工具包

runcomfy.com · GPT Image 2 edit endpoint · docs
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
runcomfy.com · GPT Image 2编辑接口 · 文档
RunComfy上的Codex Pet生成工具。将一张源图片转换为兼容Codex的自定义Codex Pet——包含
pet.json
和
spritesheet.webp
文件——将其放入
${CODEX_HOME:-$HOME/.codex}/pets/<name>/
目录后，Codex就会将其识别为自定义宠物，与内置的8款Codex Pet并列。
bash
npx skills add agentspace-so/runcomfy-agent-skills --skill codex-pet -g

What a Codex Pet is

什么是Codex Pet

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.
OpenAI Codex Pets（2026年5月发布）是像素风格的动画陪伴角色，在Codex编写代码时会悬浮在你的桌面上方——它们会响应鼠标交互和Codex的状态（思考时挠头，任务完成时弹出对话气泡）。Codex内置了8款Codex Pet，同时支持将自定义Codex Pet安装在本地
${CODEX_HOME:-$HOME/.codex}/pets/
目录下的文件夹中。
每个自定义Codex Pet文件夹包含两个文件：
  • pet.json
    ——清单文件，包含
    id
    、
    displayName
    、
    description
    、
    spritesheetPath
    字段。
  • spritesheet.webp
    ——Codex Pet精灵图集，1536x1872像素的PNG或WebP格式，8列×9行的192x208像素单元格，背景透明。
9行分别对应Codex播放的9种动画状态。每行使用固定数量的起始帧，后续单元格保持完全透明。

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

为什么选择这款Codex Pet技能（对比OpenAI官方的
hatch-pet
）

OpenAI ships an official 
hatch-pet
 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.
OpenAI官方提供了
hatch-pet
技能，通过Codex内部的
$imagegen
系统技能生成相同的Codex Pet文件（需要Codex Pro且配置了
$imagegen
）。
这款Codex Pet技能是可直接替代的方案，通过RunComfy CLI运行：仅需一个
RUNCOMFY_TOKEN
，以及
runcomfy
和
magick
二进制文件——无需Codex Pro、无需
$imagegen
、无需OPENAI_API_KEY。生成的Codex Pet文件完全一致——相同的
pet.json
结构、相同的1536x1872像素
spritesheet.webp
图集、相同的9行动画——因此Codex会将其视为与
hatch-pet
生成的宠物完全相同的自定义宠物。
该技能遵循Codex内置宠物的相同模式：一个标准姿态，通过ImageMagick微变换复制到各个单元格以实现微妙动画（1-2像素位移、眨眼帧、倾斜帧）。这与官方
hatch-pet
生成的单元格效果完全一致——Codex桌面应用中的宠物动画设计初衷就是保持微妙。
在以下场景选择该技能：
  • 你想要自定义Codex Pet，但没有Codex Pro / 
    $imagegen
    权限。
  • 你希望通过RunComfy Model API构建自定义Codex Pet。
  • 你需要批量生成Codex Pet（从源图片文件夹中生成，每个宠物仅调用一次标准接口）。
  • 你要参加OpenAI Codex Pet竞赛，希望使用不同模型生成视觉效果。
  • 你明确说出了“codex pet”、“/hatch”、“make me a codex pet”、“spritesheet.webp”、“desktop pet for codex”等指令。

Codex Pet animation rows

Codex Pet动画行说明

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.
RowStateUsed columnsFramesCodex Pet behavior
0idle0-56calm breathing/blinking; the reduced-motion first frame for the Codex Pet
1running-right0-78Codex Pet locomotion to the right
2running-left0-78mirrored locomotion to the left
3waving0-34greeting / attention gesture
4jumping0-45anticipation, lift, peak, descent, settle
5failed0-78error / sad / deflated reaction
6waiting0-56patient idle variant
7running0-56active working / in-progress loop (NOT foot-running)
8review0-56focused / inspecting / thinking
Trailing cells after each row's last used column must be fully transparent.
Codex读取固定格式的图集：8列、9行，每个单元格192x208像素。每一行对应一种动画状态，使用特定数量的起始帧。
行号状态使用列数帧数Codex Pet行为
0idle0-56平静呼吸/眨眼；Codex Pet的简化运动首帧
1running-right0-78Codex Pet向右移动
2running-left0-78向左镜像移动
3waving0-34问候/吸引注意力的动作
4jumping0-45准备、抬起、最高点、下落、落地
5failed0-78错误/悲伤/泄气的反应
6waiting0-56耐心等待的空闲变体
7running0-56活跃工作/进行中循环（非跑动动作）
8review0-56专注/检查/思考状态
每行最后一个使用列之后的后续单元格必须保持完全透明。

Codex Pet style

Codex Pet风格规范

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.
Codex Pet的视觉风格要求：
  • 夸张的Q版比例：头部占整体身高的约60%；身体和四肢短小粗壮。整个角色应接近正方形的边界框。
  • 类像素风格的低分辨率吉祥物，轮廓厚重
  • 1-2像素粗的深色轮廓，可见阶梯状像素边缘
  • 有限配色、平涂阴影、简洁生动的面部、细小四肢
  • 透明背景
避免：运动线条、投影、光晕、闪光、悬浮效果、文字标签、场景、白/黑背景。

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.
  1. RunComfy CLI — 执行
    npm i -g @runcomfy/cli
    安装
  2. RunComfy账户 — 执行
    runcomfy login
    登录。CI环境替代方案：设置
    RUNCOMFY_TOKEN=<token>
    环境变量。
  3. ImageMagick — macOS执行
    brew install imagemagick
    安装，Linux执行
    apt-get install imagemagick
    安装。提供
    magick
    命令用于确定性图集组装。
  4. 源图片URL — 可公开访问的HTTPS链接，格式为JPEG/PNG/WebP，将作为Codex Pet的原型。

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

Codex Pet生成流程（1次GPT Image 2调用，约2分钟）

  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.
  1. 标准Codex Pet生成 — 调用一次
    runcomfy run openai/gpt-image-2/edit
    ，生成一张1024x1024像素的Q版姿态图片，背景为品红色抠图底色。
  2. 单元格标准化 — 将品红色抠图底色转为透明，裁剪到宠物精灵边界框，按比例适配到192x208像素，透明区域填充空白。
  3. 程序化生成9行动画条 — 针对9种动画状态，通过ImageMagick微变换（平移/遮罩/镜像）将标准单元格生成每行的8个单元格。后续未使用的单元格填充192x208像素的透明区域。
  4. 图集拼接 — 将9行动画条垂直堆叠成1536x1872像素的Codex Pet图集。
  5. 转WebP格式 — 将PNG格式的图集转换为WebP格式。
  6. 清单文件与安装 — 生成
    pet.json
    文件，将两个文件复制到
    ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
    目录。
这种微变换方法与Codex内置宠物的实现方式一致——宠物动画设计初衷是微妙，因此每个单元格仅需1-2像素的位移和眨眼遮罩，即可实现自然的视觉效果，无需调用72次GPT Image 2接口。

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

步骤1：生成标准Codex Pet（1次调用）

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}"
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

步骤2：将标准图片标准化为192x208像素的Codex Pet单元格

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 18% fuzz is tuned for GPT Image 2's anti-aliased magenta edges. Adjust to 25% if the Codex Pet has wider magenta halos, or to 8-10% if the pet has near-magenta highlights getting clipped.
将品红色底色转为透明，裁剪到宠物精灵边界框，按比例适配到192x208像素，透明区域填充空白。
bash
magick "${BASE}" \
  -fuzz 18% -transparent "${CHROMA}" \
  -alpha set \
  -trim +repage \
  -resize 192x208 \
  -gravity center \
  -background none \
  -extent 192x208 \
  "${RUN_DIR}/cell.png"
18%的模糊度是针对GPT Image 2生成的品红色边缘抗锯齿效果调整的。如果Codex Pet有较宽的品红色光晕，可调整为25%；如果宠物有接近品红色的高光被误裁剪，可调整为8-10%。

Step 3: Build the 9 Codex Pet row strips programmatically

步骤3：程序化生成9行Codex Pet动画条

For each row, build 8 cells from the canonical via ImageMagick micro-transforms, fill unused trailing cells with transparent, then concatenate into a 1536x208 row strip.
bash
SRC="${RUN_DIR}/cell.png"
mkdir -p "${RUN_DIR}/cells"
针对每一行，通过ImageMagick微变换从标准单元格生成8个单元格，未使用的后续单元格填充透明区域，然后拼接成1536x208像素的行动画条。
bash
SRC="${RUN_DIR}/cell.png"
mkdir -p "${RUN_DIR}/cells"

Helpers

辅助函数

shift_cell() { magick "$SRC" -background none -roll "+${1}+${2}" -alpha set "$3"; } rotate_cell() { magick "$SRC" -background none -distort SRT "$1" -alpha set "$2"; } make_blink() {

Eyes are roughly at y=80-100 in a 208-tall cell.

Soften with a skin-tone overlay across that horizontal band.

magick "$SRC"
-region 80x6+56+82 -fill "#f4e6d8" -colorize 70% -blur 0x0.5 +region "$1" } blank_cell() { magick -size 192x208 xc:none -alpha set "PNG32:$1"; }
build_row() { local row=$1; shift local i=0 for spec in "$@"; do local out="${RUN_DIR}/cells/row${row}-frame${i}.png" case "$spec" in base) cp "$SRC" "$out" ;; blink) make_blink "$out" ;; shift:) IFS=':' read -r _ x y <<< "$spec"; shift_cell "$x" "$y" "$out" ;; rotate:) IFS=':' read -r _ ang <<< "$spec"; rotate_cell "$ang" "$out" ;; esac i=$((i+1)) done while [ "$i" -lt 8 ]; do blank_cell "${RUN_DIR}/cells/row${row}-frame${i}.png" i=$((i+1)) done magick "${RUN_DIR}/cells/row${row}-frame"*.png +append -alpha set
"${RUN_DIR}/cells/row${row}-strip.png" }
shift_cell() { magick "$SRC" -background none -roll "+${1}+${2}" -alpha set "$3"; } rotate_cell() { magick "$SRC" -background none -distort SRT "$1" -alpha set "$2"; } make_blink() {

眼睛大致位于208像素高单元格的y=80-100位置。

在该水平区域叠加肤色图层实现柔化效果。

magick "$SRC"
-region 80x6+56+82 -fill "#f4e6d8" -colorize 70% -blur 0x0.5 +region "$1" } blank_cell() { magick -size 192x208 xc:none -alpha set "PNG32:$1"; }
build_row() { local row=$1; shift local i=0 for spec in "$@"; do local out="${RUN_DIR}/cells/row${row}-frame${i}.png" case "$spec" in base) cp "$SRC" "$out" ;; blink) make_blink "$out" ;; shift:) IFS=':' read -r _ x y <<< "$spec"; shift_cell "$x" "$y" "$out" ;; rotate:) IFS=':' read -r _ ang <<< "$spec"; rotate_cell "$ang" "$out" ;; esac i=$((i+1)) done while [ "$i" -lt 8 ]; do blank_cell "${RUN_DIR}/cells/row${row}-frame${i}.png" i=$((i+1)) done magick "${RUN_DIR}/cells/row${row}-frame"*.png +append -alpha set
"${RUN_DIR}/cells/row${row}-strip.png" }

9 Codex Pet rows with their per-frame micro-transforms

9行Codex Pet的逐帧微变换配置

build_row 0 base base blink base base blink # idle (6) build_row 1 base shift:1:0 shift:2:-1 shift:1:0 base shift:-1:0 shift:-2:-1 shift:-1:0 # running-right (8)
build_row 0 base base blink base base blink # idle (6) build_row 1 base shift:1:0 shift:2:-1 shift:1:0 base shift:-1:0 shift:-2:-1 shift:-1:0 # running-right (8)

row 2 = running-left = horizontal flip of row 1, built below

row 2 = running-left = row 1的水平翻转，下方单独生成

build_row 3 base shift:0:-1 base shift:0:-1 # waving (4) build_row 4 shift:0:2 base shift:0:-8 shift:0:-2 base # jumping (5) — vertical arc build_row 5 base shift:0:1 rotate:1 shift:0:1 shift:0:2 shift:0:1 rotate:-1 base # failed (8) build_row 6 base base shift:0:-1 base base shift:0:1 # waiting (6) build_row 7 base shift:0:-1 base shift:0:-1 base shift:0:-1 # running (6) build_row 8 base rotate:-2 base rotate:2 base base # review (6)
build_row 3 base shift:0:-1 base shift:0:-1 # waving (4) build_row 4 shift:0:2 base shift:0:-8 shift:0:-2 base # jumping (5) — 垂直弧线 build_row 5 base shift:0:1 rotate:1 shift:0:1 shift:0:2 shift:0:1 rotate:-1 base # failed (8) build_row 6 base base shift:0:-1 base base shift:0:1 # waiting (6) build_row 7 base shift:0:-1 base shift:0:-1 base shift:0:-1 # running (6) build_row 8 base rotate:-2 base rotate:2 base base # review (6)

Row 2: running-left = mirror of running-right

Row 2: running-left = running-right的镜像翻转

magick "${RUN_DIR}/cells/row1-strip.png" -flop -alpha set "${RUN_DIR}/cells/row2-strip.png"

The micro-transform table is what gives the Codex Pet its readable-but-subtle motion in Codex. Tweak the numbers per row to taste; the deltas are intentionally small (1-2 px) so the Codex Pet feels alive without becoming distracting.
magick "${RUN_DIR}/cells/row1-strip.png" -flop -alpha set "${RUN_DIR}/cells/row2-strip.png"

微变换配置是Codex Pet在Codex中呈现自然微妙动画的关键。可根据喜好调整每行的参数；参数变化应保持较小（≤4像素或≤4°），避免宠物动画过于分散注意力。

Step 4: Compose the Codex Pet atlas

步骤4：拼接Codex Pet图集

Stack the 9 row strips vertically into the 1536x1872 Codex Pet atlas, then convert to WebP.
bash
magick \
  "${RUN_DIR}/cells/row0-strip.png" \
  "${RUN_DIR}/cells/row1-strip.png" \
  "${RUN_DIR}/cells/row2-strip.png" \
  "${RUN_DIR}/cells/row3-strip.png" \
  "${RUN_DIR}/cells/row4-strip.png" \
  "${RUN_DIR}/cells/row5-strip.png" \
  "${RUN_DIR}/cells/row6-strip.png" \
  "${RUN_DIR}/cells/row7-strip.png" \
  "${RUN_DIR}/cells/row8-strip.png" \
  -append -alpha set "${RUN_DIR}/spritesheet.png"

magick "${RUN_DIR}/spritesheet.png" "${RUN_DIR}/spritesheet.webp"
将9行动画条垂直堆叠成1536x1872像素的Codex Pet图集，然后转换为WebP格式。
bash
magick \
  "${RUN_DIR}/cells/row0-strip.png" \
  "${RUN_DIR}/cells/row1-strip.png" \
  "${RUN_DIR}/cells/row2-strip.png" \
  "${RUN_DIR}/cells/row3-strip.png" \
  "${RUN_DIR}/cells/row4-strip.png" \
  "${RUN_DIR}/cells/row5-strip.png" \
  "${RUN_DIR}/cells/row6-strip.png" \
  "${RUN_DIR}/cells/row7-strip.png" \
  "${RUN_DIR}/cells/row8-strip.png" \
  -append -alpha set "${RUN_DIR}/spritesheet.png"

magick "${RUN_DIR}/spritesheet.png" "${RUN_DIR}/spritesheet.webp"

Step 5: Write the Codex Pet manifest

步骤5：生成Codex Pet清单文件

bash
cat > "${RUN_DIR}/pet.json" <<EOF
{
  "id": "${PET_NAME}",
  "displayName": "${PET_NAME}",
  "description": "${PET_DESC}",
  "spritesheetPath": "spritesheet.webp"
}
EOF
bash
cat > "${RUN_DIR}/pet.json" <<EOF
{
  "id": "${PET_NAME}",
  "displayName": "${PET_NAME}",
  "description": "${PET_DESC}",
  "spritesheetPath": "spritesheet.webp"
}
EOF

Step 6: Install the Codex Pet

步骤6：安装Codex Pet

bash
DEST="${CODEX_HOME:-$HOME/.codex}/pets/${PET_NAME}"
mkdir -p "${DEST}"
cp "${RUN_DIR}/pet.json" "${RUN_DIR}/spritesheet.webp" "${DEST}/"
echo "Codex Pet installed at ${DEST}"
Restart Codex (or reload the pet list) and the custom Codex Pet appears next to the 8 built-ins.
bash
DEST="${CODEX_HOME:-$HOME/.codex}/pets/${PET_NAME}"
mkdir -p "${DEST}"
cp "${RUN_DIR}/pet.json" "${RUN_DIR}/spritesheet.webp" "${DEST}/"
echo "Codex Pet installed at ${DEST}"
重启Codex（或重新加载宠物列表），自定义Codex Pet就会出现在内置的8款宠物旁边。

Prompting the canonical Codex Pet — what works

标准Codex Pet提示词技巧

The single GPT Image 2 call decides everything. Get this prompt right and the rest is deterministic.
Lead with the chibi proportion lock. "EXAGGERATED chibi proportions, head ~60 percent of figure height" is the difference between a thin tall character (which fits the 192x208 cell badly with pillarbox) and a head-dominant chibi (which fills the cell naturally). The latter is what Codex's built-in Codex Pets look like.
Demand the magenta 
#FF00FF
chroma-key explicitly in every Codex Pet base prompt. GPT Image 2 only outputs RGB (no alpha), so the only way to get a transparent Codex Pet is to chroma-key a known background color out post-process.
Forbid the chroma-key color in the pet itself. Add: "The pet itself must not use the chroma-key color or any close-to-magenta highlights." Otherwise the chroma-key step removes Codex Pet body parts that happen to be magenta-ish.
Pin the style. "pixel-art-adjacent, chunky silhouette, 1-2 px outline, limited palette, flat cel shading" — pin every term that makes the Codex Pet match the Codex house style.
Forbid the wrong styles. "No polished illustration, no painterly render, no anime key art, no 3D render, no glossy app-icon polish, no realistic detail." Without this, GPT Image 2 will gravitate toward over-rendered anime art.
Anti-patterns:
  • Generic "transparent background" — GPT Image 2 paints near-white instead. Use chroma-key.
  • Letting the model freestyle proportions — it will draw a tall narrow chibi that doesn't fit 192x208.
  • Mixing styles in one prompt — pin one style anchor and stick to it.
单次GPT Image 2调用决定了最终效果。提示词设置正确后，后续流程都是确定性的。
优先锁定Q版比例。“EXAGGERATED chibi proportions, head ~60 percent of figure height”是区分瘦高角色（难以适配192x208单元格，会出现黑边）和大头Q版角色（自然填充单元格）的关键。后者与Codex内置宠物的风格一致。
明确要求品红色
#FF00FF
抠图底色。GPT Image 2仅输出RGB格式（无透明通道），因此后期通过抠图去除已知背景色是获得透明宠物的唯一方法。
禁止宠物使用抠图底色。添加：“The pet itself must not use the chroma-key color or any close-to-magenta highlights.”否则抠图步骤会误删除宠物身上接近品红色的部分。
固定风格。“pixel-art-adjacent, chunky silhouette, 1-2 px outline, limited palette, flat cel shading”——明确所有符合Codex风格的术语。
禁止错误风格。“No polished illustration, no painterly render, no anime key art, no 3D render, no glossy app-icon polish, no realistic detail.”如果不添加这些，GPT Image 2会倾向于生成过度渲染的动漫风格图片。
反模式：
  • 泛泛的“transparent background”——GPT Image 2会生成接近白色的背景，应使用抠图底色。
  • 让模型自由定义比例——它会生成瘦高的Q版角色，无法适配192x208单元格。
  • 在一个提示词中混合多种风格——固定一种风格并坚持使用。

Tuning the micro-animation

微动画调整

The default ImageMagick recipe in step 3 produces a Codex Pet animation similar to the built-in Codex Pets — subtle bob, occasional blink, jumping arc, head tilt. To make the animation more or less perceptible, tweak the deltas:
  • Bigger idle bob: change 
    shift:0:-1
    to 
    shift:0:-2
    in row 0.
  • Faster running cycle: increase the horizontal shifts in row 1 (e.g. 
    shift:3:0
    instead of 
    shift:2:-1
    ).
  • Higher jump: change row 4's peak from 
    shift:0:-8
    to 
    shift:0:-12
    .
  • Stronger head tilt in review: change 
    rotate:-2
    / 
    rotate:2
    to 
    rotate:-4
    / 
    rotate:4
    .
Keep deltas small (≤ 4 px or ≤ 4°) so the Codex Pet doesn't become distracting.
步骤3中的默认ImageMagick配置生成的Codex Pet动画与内置宠物类似——微妙的晃动、偶尔眨眼、跳跃弧线、头部倾斜。如需调整动画的明显程度，可修改参数：
  • 更明显的空闲晃动：将第0行的
    shift:0:-1
    改为
    shift:0:-2
    。
  • 更快的跑动循环：增加第1行的水平位移（例如将
    shift:2:-1
    改为
    shift:3:0
    ）。
  • 更高的跳跃：将第4行的峰值位移从
    shift:0:-8
    改为
    shift:0:-12
    。
  • 更明显的思考时头部倾斜：将第8行的
    rotate:-2
    /
    rotate:2
    改为
    rotate:-4
    /
    rotate:4
    。
参数变化应保持较小（≤4像素或≤4°），避免宠物动画过于分散注意力。

FAQ — Codex Pet

FAQ — Codex Pet

What is a Codex Pet? OpenAI Codex Pets are pixel-art animated companions launched May 2026 that float over your desktop and react to Codex's coding status. Custom Codex Pets live as 
pet.json
+ 
spritesheet.webp
files under 
${CODEX_HOME:-$HOME/.codex}/pets/<name>/
.
Why use this Codex Pet skill instead of 
hatch-pet
? Official 
hatch-pet
requires the Codex-internal 
$imagegen
system skill (Codex Pro). This skill needs only 
RUNCOMFY_TOKEN
and runs the same animation-row spec via the RunComfy CLI, with one GPT Image 2 call total.
How long does a Codex Pet generation take? ~2 minutes — 1 GPT Image 2 edit call (~90s) plus a few seconds of ImageMagick atlas assembly.
Why only one API call? The Codex Pet animation in the Codex desktop app is intentionally subtle (you can confirm by inspecting any built-in Codex Pet's atlas — 72 cells of nearly-identical poses with tiny variations). One canonical pose plus deterministic ImageMagick micro-transforms produces the same animation feel without burning 72 separate generation calls.
Can the Codex Pet skill take a non-human subject? Yes — pets, mascots, objects, foods all work. The base prompt simplifies the source into the Codex Pet house style automatically.
How do I install my Codex Pet? Copy 
pet.json
and 
spritesheet.webp
into 
${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
and reload Codex.
What if the canonical Codex Pet drifts off identity? Re-run step 1 with a tighter identity-preservation prompt (e.g. name specific features: hair color, glasses, accessory). Steps 2-6 are deterministic and don't need to change.
What size is each Codex Pet frame? 192x208 px. Each row strip is 1536x208 (8 frames). Final Codex Pet atlas is 1536x1872 (9 stacked rows).
Can I add custom poses or replace rows? Yes — modify the 
build_row
calls in step 3. The atlas slot count per row must match the Codex contract (idle=6, running-right/left=8, waving=4, jumping=5, failed=8, waiting/running/review=6) for Codex to play them correctly.
什么是Codex Pet？ OpenAI Codex Pets是2026年5月推出的像素风格动画陪伴角色，会悬浮在桌面上方并响应Codex的编码状态。自定义Codex Pet以
pet.json
和
spritesheet.webp
文件的形式存放在
${CODEX_HOME:-$HOME/.codex}/pets/<name>/
目录下。
为什么使用这款Codex Pet技能而不是
hatch-pet
？ 官方
hatch-pet
需要Codex内部的
$imagegen
系统技能（需Codex Pro）。这款技能仅需
RUNCOMFY_TOKEN
，通过RunComfy CLI运行相同的动画行规范，仅需调用一次GPT Image 2接口。
生成一个Codex Pet需要多长时间？ 约2分钟——1次GPT Image 2编辑调用（约90秒）加上几秒的ImageMagick图集组装时间。
为什么只调用一次API？ Codex桌面应用中的宠物动画设计初衷是微妙（你可以查看任何内置宠物的图集确认——72个单元格几乎都是相同姿态，仅存在微小差异）。一个标准姿态加上确定性的ImageMagick微变换即可实现相同的动画效果，无需调用72次生成接口。
Codex Pet技能支持非人类主题吗？ 是的——宠物、吉祥物、物品、食物都可以。基础提示词会自动将源图片简化为Codex Pet风格。
如何安装Codex Pet？ 将
pet.json
和
spritesheet.webp
复制到
${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
目录，然后重新加载Codex。
如果标准Codex Pet与源图片差异过大怎么办？ 重新运行步骤1，使用更严格的身份保留提示词（例如指定具体特征：头发颜色、眼镜、配饰）。步骤2-6是确定性的，无需修改。
每个Codex Pet帧的尺寸是多少？ 192x208像素。每行动画条是1536x208像素（8帧）。最终Codex Pet图集是1536x1872像素（9行堆叠）。
我可以添加自定义姿态或替换行吗？ 可以——修改步骤3中的
build_row
调用。每行的图集插槽数量必须符合Codex的规范（idle=6、running-right/left=8、waving=4、jumping=5、failed=8、waiting/running/review=6），Codex才能正确播放。

Limitations

局限性

  • One canonical pose per Codex Pet — animation is via ImageMagick transforms, not multi-frame model generation. This matches the built-in Codex Pets' subtle animation but won't produce dramatic motion (e.g. distinct frame-by-frame running cycle).
  • GPT Image 2 doesn't output alpha — the magenta chroma-key + post-process is a workaround. If the Codex Pet has near-magenta colors (rare for chibi palettes), switch the chroma-key to a different solid (
    #00FFFF
    cyan or 
    #00FF00
    green) in both the prompt and the post-process.
  • Identity drift — GPT Image 2 may simplify the source image identity into Codex Pet style; specific small features (e.g. earrings, prop colors) may shift.
  • No audio / voice on Codex Pet — Codex Pets are visual-only.
  • 每个Codex Pet仅一个标准姿态——动画通过ImageMagick变换实现，而非多帧模型生成。这与内置宠物的微妙动画一致，但无法生成剧烈动作（例如逐帧不同的跑动循环）。
  • GPT Image 2不输出透明通道——品红色抠图+后期处理是一种 workaround。如果Codex Pet有接近品红色的颜色（Q版配色中很少见），可将抠图底色改为其他纯色（
    #00FFFF
    青色或
    #00FF00
    绿色），并同步修改提示词和后期处理步骤。
  • 身份偏差——GPT Image 2可能会将源图片的特征简化为Codex Pet风格；特定小特征（例如耳环、道具颜色）可能会发生变化。
  • Codex Pet无音频/语音——Codex Pet仅支持视觉效果。

Exit codes

退出码

The 
runcomfy
CLI uses sysexits-style codes:
codemeaning
0Codex Pet canonical generated successfully
64bad CLI args
65bad input JSON for the Codex Pet call / schema mismatch (e.g. 
size: "1024_1024"
instead of 
"1024*1024"
)
69upstream 5xx
75retryable: timeout / 429
77not signed in or token rejected
magick
(ImageMagick) returns 0 on a clean Codex Pet atlas; non-zero indicates a missing input frame or output-path permission issue.
Full reference: docs.runcomfy.com/cli/troubleshooting.
runcomfy
CLI使用sysexits风格的退出码：
代码含义
0标准Codex Pet生成成功
64CLI参数错误
65Codex Pet调用的输入JSON错误/ schema不匹配（例如
size: "1024_1024"
而非
"1024*1024"
）
69上游服务5xx错误
75可重试：超时/429错误
77未登录或令牌被拒绝
magick
（ImageMagick）在图集组装成功时返回0；非零值表示缺少输入帧或输出路径权限问题。
完整参考：docs.runcomfy.com/cli/troubleshooting。

How it works

工作原理

  1. The skill calls 
    runcomfy run openai/gpt-image-2/edit
    once with the user's source image and a tight chibi-proportion prompt, producing a 1024x1024 canonical Codex Pet on magenta.
  2. ImageMagick chroma-keys the magenta to alpha 0, trims the sprite bbox, aspect-fits into a 192x208 cell.
  3. ImageMagick programmatically builds 9 row strips by applying micro-transforms (1-2 px translate, blink mask, rotate, mirror) to the canonical cell.
  4. The 9 row strips stack into the 1536x1872 Codex Pet atlas; the atlas converts to WebP.
  5. A 
    pet.json
    manifest is written; both files are copied into 
    ${CODEX_HOME:-$HOME/.codex}/pets/<name>/
    where Codex picks up the custom Codex Pet automatically.
  1. 技能调用
    runcomfy run openai/gpt-image-2/edit
    一次，传入用户的源图片和严格的Q版比例提示词，生成一张1024x1024像素的标准Codex Pet图片，背景为品红色。
  2. ImageMagick将品红色转为透明，裁剪到精灵边界框，按比例适配到192x208像素的单元格。
  3. ImageMagick通过微变换（1-2像素平移、眨眼遮罩、旋转、镜像）从标准单元格程序化生成9行动画条。
  4. 将9行动画条堆叠成1536x1872像素的Codex Pet图集，并转换为WebP格式。
  5. 生成
    pet.json
    清单文件，将两个文件复制到
    ${CODEX_HOME:-$HOME/.codex}/pets/<name>/
    目录，Codex会自动识别该自定义Codex Pet。

Credits

致谢

The 9-row Codex Pet atlas spec — column counts, frame counts, cell dimensions — comes from OpenAI's official 
hatch-pet
 skill (MIT licensed). The animation-row contract and the chroma-key strategy are documented there. This skill reuses the spec but swaps the visual generator (
$imagegen
→ RunComfy GPT Image 2) and the atlas assembly (Python → ImageMagick) so it runs without Codex Pro.
9行Codex Pet图集规范——列数、帧数、单元格尺寸——来自OpenAI官方的
hatch-pet
技能（MIT许可证）。动画行规范和抠图策略均来自该技能的文档。本技能复用了该规范，但替换了视觉生成器（
$imagegen
→ RunComfy GPT Image 2）和图集组装方式（Python → ImageMagick），使其无需Codex Pro即可运行。

What this skill is not

本技能不包含的内容

Not a Codex client. Not a 
hatch-pet
replacement when 
$imagegen
is available — official 
hatch-pet
is preferable when Codex Pro is in play. Not a self-hosted GPT Image 2 — depends on a working RunComfy account.
不是Codex客户端。当
$imagegen
可用时，不是
hatch-pet
的替代方案——官方
hatch-pet
在拥有Codex Pro时更优。不是自托管的GPT Image 2——依赖可用的RunComfy账户。

Security & Privacy

安全与隐私

  • Token storage: 
    runcomfy login
    writes the API token to 
    ~/.config/runcomfy/token.json
    with mode 0600. Set 
    RUNCOMFY_TOKEN
    env var to bypass the file in CI.
  • Input boundary: Codex Pet prompts are passed as JSON via 
    --input
    . The CLI does NOT shell-expand. No shell-injection surface.
  • Third-party content: source image URL is fetched by the RunComfy server. Treat external URLs as untrusted — image-based prompt injection is a known risk for any image-edit model.
  • Outbound endpoints: only 
    model-api.runcomfy.net
    and 
    *.runcomfy.net
    / 
    *.runcomfy.com
    .
  • Generated-file size cap: the CLI aborts any single Codex Pet canonical download > 2 GiB.
  • Local install path: the final Codex Pet writes to 
    ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
    . No remote upload.
  • 令牌存储：
    runcomfy login
    会将API令牌写入
    ~/.config/runcomfy/token.json
    ，权限为0600。在CI环境中可设置
    RUNCOMFY_TOKEN
    环境变量绕过文件存储。
  • 输入边界：Codex Pet提示词通过
    --input
    以JSON形式传递。CLI不会进行shell扩展，不存在shell注入风险。
  • 第三方内容：源图片URL由RunComfy服务器获取。将外部URL视为不可信——基于图片的提示注入是所有图片编辑模型的已知风险。
  • 出站端点：仅访问
    model-api.runcomfy.net
    和
    *.runcomfy.net
    / 
    *.runcomfy.com
    。
  • 生成文件大小限制：CLI会中止任何超过2 GiB的标准Codex Pet下载。
  • 本地安装路径：最终Codex Pet文件写入
    ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
    目录，不会上传到远程服务器。