codex-pet

Codex Pet — RunComfy の Pro Pack

runcomfy.com · GPT Image 2 edit endpoint · ドキュメント

RunComfy 上の Codex Pet ジェネレーターです。 1 枚の元画像から Codex 互換のカスタム Codex Pet（pet.json + spritesheet.webp）を作成し、${CODEX_HOME:-$HOME/.codex}/pets/<name>/ に配置すると、Codex は 8 種類の組み込み Codex Pet と並べて読み込みます。

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

Codex Pet とは

OpenAI Codex Pets（2026 年 5 月リリース）は、Codex がコードを書いている間、デスクトップ上に浮かんで表示されるピクセルアートのアニメーション付きコンパニオンです。マウス操作や Codex の状態に反応し、思考中には頭をかき、タスクが完了すると吹き出しを表示します。Codex には 8 種類の Codex Pet が組み込まれており、${CODEX_HOME:-$HOME/.codex}/pets/ の下にフォルダーとしてインストールしたカスタム Codex Pet にも対応しています。

各カスタム Codex Pet フォルダーには、次の 2 つのファイルだけが含まれます。

• pet.json — id、displayName、description、spritesheetPath を含むマニフェストです。
• spritesheet.webp — Codex Pet のスプライトアトラスです。透明背景の 1536x1872 の PNG または WebP で、192x208 のセルが 8 列 x 9 行に並んでいます。

9 行は、Codex が再生する 9 種類のアニメーション状態に対応します。各行で使用するのは先頭から一定数のフレームで、残りのセルは完全に透明のままです。

この Codex Pet スキルを選ぶ理由（OpenAI 公式の hatch-pet との比較）

OpenAI は、Codex 内部の $imagegen システムスキルを使って同じ Codex Pet アーティファクトを生成する、公式の hatch-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 はこの Codex Pet を hatch-pet で作成したものとまったく同じように扱います。

このスキルは、Codex の組み込み Codex Pets と同じパターンに従います。1 つの標準ポーズを ImageMagick の微細な変換で各セルに複製し、わずかなアニメーション（1～2 px の移動、まばたきフレーム、傾きフレーム）を作成します。これは、公式の hatch-pet の出力をセルごとに見たときの見た目と一致します。Codex デスクトップアプリで表示される Codex Pet のアニメーションは、意図的に控えめにしてあります。

次のような場合に、このスキルをお選びください。

• カスタム Codex Pet を作成したいものの、Codex Pro や $imagegen を利用できない場合。
• RunComfy Model API を使ってカスタム Codex Pet を作成したい場合。
• 元画像のフォルダーからカスタム Codex Pet を一括生成したい場合（ペットごとに標準ポーズを 1 回生成）。
• ビジュアルの生成に異なるモデルを使って、OpenAI Codex Pet コンテストに参加する場合。
• 「codex pet」、「/hatch」、「make me a codex pet」、「spritesheet.webp」、「desktop pet for codex」と明示的に指定された場合。

Codex Pet のアニメーション行

Codex は固定のアトラスを読み込みます。8 列、9 行で、セルのサイズは 192x208 です。各 Codex Pet の行は、先頭フレーム数が異なる 1 つのアニメーション状態に対応します。

行	状態	使用列	フレーム数	Codex Pet の動作
0	idle	0-5	6	穏やかな呼吸とまばたき。Codex Pet の低モーション設定時に使う最初のフレーム
1	running-right	0-7	8	Codex Pet が右へ移動
2	running-left	0-7	8	左への移動を反転表示
3	waving	0-3	4	あいさつ／注意を引くジェスチャー
4	jumping	0-4	5	予備動作、上昇、頂点、下降、着地
5	failed	0-7	8	エラー／悲しみ／しょんぼりした反応
6	waiting	0-5	6	辛抱強く待つアイドル状態
7	running	0-5	6	作業中／進行中のループ（足を動かして走る動作ではありません）
8	review	0-5	6	集中／点検／思考

各行の最後に使用する列より後ろのセルは、完全に透明にしてください。

Codex Pet のスタイル

Codex Pet のビジュアルスタイル：

• 誇張されたちびキャラのプロポーション：頭部が全体の高さの約 60 パーセントを占め、胴体と脚は短く小さくします。全体が正方形に近いバウンディングボックスに収まるようにします。
• ピクセルアート風の低解像度マスコット、ずんぐりしたシルエット
• 太い暗色の 1-2 px の輪郭線、目に見える階段状のピクセルエッジ
• 限られたパレット、平面的なセルシェーディング、シンプルで表情豊かな顔、小さな手足
• 透明な背景

避けるもの：動線、ドロップシャドウ、光彩、きらめき、浮遊効果、テキストラベル、背景の風景、白または黒の背景。

前提条件

1. RunComfy CLI — npm i -g @runcomfy/cli
2. RunComfy アカウント — runcomfy login。CI での代替手段：RUNCOMFY_TOKEN=<token>。
3. ImageMagick — brew install imagemagick（macOS）または apt-get install imagemagick（Linux）。決定論的なアトラスの組み立てに使う magick コマンドが提供されます。
4. ソース画像の URL — 公開アクセス可能な HTTPS の JPEG/PNG/WebP 画像で、Codex Pet のモデルにする対象が写っているもの。

Codex Pet のパイプライン（GPT Image 2 の呼び出し 1 回、約 2 分）

1. 標準 Codex Pet — runcomfy run openai/gpt-image-2/edit を 1 回呼び出し、マゼンタのクロマキー背景上に 1024x1024 のちびキャラのポーズを 1 つ生成します。
2. セルの正規化 — クロマキーのマゼンタをアルファ 0 にし、トリミングしてから、透明な余白を付けて 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 に組み込まれた Codex Pets の実際の動作に合わせたものです。Codex Pet のアニメーションは意図的に控えめなので、セルごとに 1-2 px の移動とまばたきマスクを使うことで、GPT Image 2 を 72 回呼び出さずに適切な見た目を実現できます。

ステップ 1：標準 Codex Pet を生成する（1 回の呼び出し）

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

ステップ 2：標準画像を 192x208 の Codex Pet セルに正規化する

クロマキーのマゼンタをアルファに変換し、ペットのスプライトのバウンディングボックスに合わせてトリミングしてから、透明な余白を付けて 192x208 にアスペクトフィットします。

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% に調整してください。

ステップ 3：9 行の Codex Pet ストリップをプログラムで作成する

各行について、ImageMagick のマイクロ変換を使って標準画像から 8 セルを作成し、未使用の末尾セルを透明にした後、連結して 1536x208 の行ストリップにします。

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

# 9 Codex Pet rows with their per-frame micro-transforms
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
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)

# Row 2: running-left = mirror of running-right
magick "${RUN_DIR}/cells/row1-strip.png" -flop -alpha set "${RUN_DIR}/cells/row2-strip.png"

マイクロ変換テーブルにより、Codex Pet は Codex 上で分かりやすく、かつ控えめな動きをします。各行の数値は好みに合わせて調整してください。Codex Pet が生き生きとしながらも注意をそらさないよう、差分は意図的に小さく（1-2 px）してあります。

ステップ 4：Codex Pet のアトラスを作成する

9 個の行ストリップを縦に並べて、1536x1872 の Codex Pet アトラスを作成し、WebP に変換します。

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"

ステップ 5：Codex Pet のマニフェストを作成する

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

ステップ 6：Codex Pet をインストールする

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 個のペットの隣に表示されます。

公式 Codex Pet のプロンプト — 効果的な方法

1 回の GPT Image 2 呼び出しですべてが決まります。このプロンプトを適切に設定すれば、あとは決定的な処理になります。

まず、ちびキャラのプロポーションを固定します。 「誇張したちびキャラのプロポーション。頭部はキャラクターの高さの約 60 パーセント」と指定することで、（192x208 のセルに合わず、左右に余白ができる）細長いキャラクターではなく、セルに自然に収まる頭の大きなちびキャラになります。Codex の組み込み Codex Pet の見た目は後者です。

Codex Pet のベースプロンプトでは、毎回マゼンタの #FF00FF クロマキーを明示的に指定します。 GPT Image 2 は RGB（アルファなし）のみを出力するため、透明な Codex Pet を作成するには、後処理で既知の背景色をクロマキーで除去する必要があります。

ペット本体にはクロマキーの色を使わないよう指定します。 「ペット本体にはクロマキーの色や、マゼンタに近いハイライトを使わないこと。」と追加します。そうしないと、クロマキー処理で、マゼンタがかった Codex Pet の体の一部まで除去されてしまいます。

スタイルを固定します。 「ピクセルアートに近い、塊感のあるシルエット、1～2 px の輪郭線、限定されたパレット、フラットなセルシェーディング」と指定し、Codex のハウススタイルに Codex Pet を合わせるための要素をすべて固定します。

不適切なスタイルを禁止します。 「洗練されたイラスト、絵画風のレンダリング、アニメのキービジュアル、3D レンダリング、光沢のあるアプリアイコンのような仕上げ、リアルなディテールは不可。」と指定します。これを指定しないと、GPT Image 2 は過剰に描き込まれたアニメ風の絵に傾きます。

アンチパターン：

• 「透明な背景」のような一般的な指定：GPT Image 2 は代わりに白に近い色で塗ります。クロマキーを使ってください。
• プロポーションをモデル任せにする：192x208 に収まらない、細長いちびキャラが描かれます。
• 1 つのプロンプトでスタイルを混在させる：スタイルの基準を 1 つに固定し、一貫させてください。

マイクロアニメーションの調整

ステップ 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 に変更します。
• レビュー時の首の傾きを大きくする：rotate:-2 / rotate:2 を rotate:-4 / rotate:4 に変更します。

Codex Pet が邪魔にならないよう、差分は小さく保ってください（≤ 4 px または ≤ 4°）。

FAQ — Codex Pet

Codex Pet とは何ですか？ OpenAI Codex Pets は、2026 年 5 月にリリースされたピクセルアートのアニメーション付きコンパニオンです。デスクトップ上に浮かび、Codex のコーディング状況に反応します。カスタムの Codex Pets は、${CODEX_HOME:-$HOME/.codex}/pets/<name>/ の下にある pet.json + spritesheet.webp ファイルとして保存されます。

hatch-pet ではなく、この Codex Pet スキルを使う理由は何ですか？ 公式の hatch-pet では、Codex 内部の $imagegen システムスキル（Codex Pro）が必要です。このスキルでは RUNCOMFY_TOKEN だけで済み、RunComfy CLI を使って同じアニメーション行の仕様を実行し、GPT Image 2 の呼び出しは合計 1 回です。

Codex Pet の生成にはどのくらい時間がかかりますか？ 約 2 分です。GPT Image 2 による編集呼び出しが約 90 秒、ImageMagick によるアトラスの組み立てに数秒かかります。

API 呼び出しが 1 回だけなのはなぜですか？ Codex デスクトップアプリの Codex Pet アニメーションは、意図的に控えめな動きになっています（組み込みの Codex Pet のアトラスを確認すると、わずかな違いのあるほぼ同一のポーズが 72 セル並んでいます）。基準となるポーズ 1 つと、決定論的な 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 px です。各行のストリップは 1536x208（8 フレーム）です。最終的な Codex Pet アトラスは 1536x1872（9 行を縦に積み重ねたもの）です。

カスタムポーズを追加したり、行を置き換えたりできますか？ はい。手順 3 の build_row 呼び出しを変更します。Codex で正しく再生するには、各行のアトラススロット数が Codex の仕様と一致している必要があります（idle=6、running-right/left=8、waving=4、jumping=5、failed=8、waiting/running/review=6）。

制限事項

• Codex Pet ごとに基準となるポーズは 1 つです — アニメーションは複数フレームのモデル生成ではなく、ImageMagick の変換によって作成されます。これは組み込みの Codex Pets の控えめなアニメーションには合っていますが、劇的な動き（たとえば、フレームごとに明確に変化する走行サイクル）は生成できません。
• GPT Image 2 はアルファチャンネルを出力しません — マゼンタのクロマキーと後処理で対処します。Codex Pet にマゼンタに近い色が含まれる場合（ちびキャラの配色ではまれです）、プロンプトと後処理の両方でクロマキーを別の単色（#00FFFF のシアンまたは #00FF00 の緑）に変更してください。
• アイデンティティのずれ — GPT Image 2 は元画像の特徴を Codex Pet のスタイルに合わせて簡略化する場合があります。イヤリングや小道具の色など、細かな特徴が変わることがあります。
• Codex Pet に音声やボイスはありません — Codex Pets は視覚のみです。

終了コード

runcomfy CLI は sysexits 形式のコードを使用します。

code	意味
0	Codex Pet の基準画像の生成に成功
64	CLI 引数が不正
65	Codex Pet の呼び出しに渡す入力 JSON が不正、またはスキーマが一致しない（例：size: "1024_1024" が指定されているが、正しくは "1024*1024"）
69	上流からの 5xx エラー
75	再試行可能：タイムアウト / 429
77	サインインしていない、またはトークンが拒否された

magick（ImageMagick）は、Codex Pet のアトラスが正常に生成されると 0 を返します。0 以外は、入力フレームが見つからないか、出力先のパスへのアクセス権限に問題があることを示します。

詳細なリファレンス：docs.runcomfy.com/cli/troubleshooting.

仕組み

1. スキルは、ユーザーのソース画像と、ちびキャラの比率を厳密に指定するプロンプトを使って、runcomfy run openai/gpt-image-2/edit を1回呼び出し、マゼンタ背景の標準 Codex Pet を1024x1024で生成します。
2. ImageMagick でクロマキー処理を行い、マゼンタをアルファ値0にして、スプライトの境界ボックスをトリミングし、192x208のセルに縦横比を保って収めます。
3. ImageMagick で、標準セルに微小な変換（1～2 px の平行移動、まばたきマスク、回転、反転）を適用し、9つの行ストリップをプログラムで作成します。
4. 9つの行ストリップを重ねて1536x1872の Codex Pet アトラスを作成し、アトラスを WebP に変換します。
5. pet.json マニフェストを作成し、2つのファイルを ${CODEX_HOME:-$HOME/.codex}/pets/<name>/ にコピーします。Codex はカスタム Codex Pet を自動的に認識します。

クレジット

9行の Codex Pet アトラス仕様（列数、フレーム数、セルの寸法）は、OpenAI 公式の hatch-pet スキル（MIT ライセンス）に基づいています。アニメーション行の仕様とクロマキー戦略も、同スキルで説明されています。このスキルは仕様を再利用しつつ、ビジュアル生成器（$imagegen → RunComfy GPT Image 2）とアトラスの組み立て（Python → ImageMagick）を置き換えることで、Codex Pro なしで実行できるようにしています。

このスキルの対象外

Codex クライアントではありません。$imagegen が利用可能な場合に hatch-pet の代わりとなるものではありません。Codex Pro を利用できる場合は、公式の hatch-pet が適しています。セルフホスト可能な GPT Image 2 ではありません。RunComfy アカウントが必要です。

セキュリティとプライバシー

• トークンの保存：runcomfy login は、API トークンをモード 0600 で ~/.config/runcomfy/token.json に書き込みます。CI でファイルを介さずにトークンを使うには、RUNCOMFY_TOKEN 環境変数を設定します。
• 入力の境界：Codex Pet のプロンプトは、--input を介して JSON として渡されます。CLI はシェル展開を行いません。シェルインジェクションの攻撃面はありません。
• サードパーティのコンテンツ：ソース画像の URL は RunComfy サーバーが取得します。外部 URL は信頼できないものとして扱ってください。画像ベースのプロンプトインジェクションは、あらゆる画像編集モデルに共通する既知のリスクです。
• 外部接続先：model-api.runcomfy.net および *.runcomfy.net／*.runcomfy.com のみです。
• 生成ファイルのサイズ上限：CLI は、単一の Codex Pet 標準画像のダウンロードが 2 GiB を超える場合に中断します。
• ローカルのインストール先：最終的な Codex Pet は ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/ に書き込まれます。リモートへのアップロードはありません。