Codex Pet — Pro Pack on RunComfy

runcomfy.com · GPT Image 2 edit endpoint · docs

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 Petを${CODEX_HOME:-$HOME/.codex}/pets/の下のフォルダとしてローカルにインストールすることをサポートしています。

各カスタムCodex Petフォルダには正確に2つのファイルが含まれます：

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

9つの行は9つのアニメーション状態に対応しており、Codexが再生します。各行は固定数の先頭フレームを使用します。末尾セルは完全に透明のままです。

この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シェイプ、同じspritesheet.webp 1536x1872アトラス、同じ9アニメーション行 — したがってCodexはこのCodex Petをhatch-petで作られたものと同じように処理します。

このスキルはCodexの組み込みCodex Petが使用するのと同じパターンに従います：1つの標準的なポーズは、ImageMagickマイクロトランスフォームでセル全体に複製され、微妙なアニメーションを実現します（1-2ピクセルシフト、まばたきフレーム、傾きフレーム）。これはOpenAIの公式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は1つの固定アトラスを読みます：8列、9行、192x208セル。各Codex Pet行は特定数の先頭フレームを持つ1つのアニメーション状態に対応します。

Row	State	使用列	フレーム	Codex Petの動作
0	idle	0-5	6	穏やかな呼吸/まばたき；モーション縮約の最初のフレーム
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	忍耐強いidleバリアント
7	running	0-5	6	アクティブな作業／進行中のループ（足走りではない）
8	review	0-5	6	集中／検査／思考中

各行の最後に使用した列の後の末尾セルは完全に透明である必要があります。

Codex Petスタイル

Codex Petビジュアルハウススタイル：

• 誇張されたキビプロポーション：頭は総身長の約60パーセントを占めます。体と脚は小さく太短いです。全体的な図は正方形に近いバウンディングボックスに収まる必要があります。
• ピクセルアート系の低解像度マスコット、太いシルエット
• 太い濃い1-2ピクセルのアウトライン、見える段階的なピクセルエッジ
• 限定的なパレット、フラットなセルシェーディング、シンプルな表現力豊かな顔、小さな手足
• 透明背景

避けるべき内容：モーションライン、ドロップシャドウ、グロー、スパークル、浮揚効果、テキストラベル、風景、白/黒背景。

前提条件

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パイプライン（1 GPT Image 2呼び出し、約2分）

1. 標準的なCodex Pet — 単一のruncomfy run openai/gpt-image-2/edit呼び出しで、マゼンタクロマキー背景上に1つの1024x1024キビポーズを生成します。
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 Petが実際に行うことと一致します — Codex Petアニメーションは意図的に微妙であるため、セルあたりの1-2ピクセルシフトとまばたきマスクは72の個別GPT Image 2呼び出しを消費することなく正しいビジュアルフィールを提供します。

ステップ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のアンチエイリアスマゼンタエッジに対して調整されています。ペットに広いマゼンタハローがある場合は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行とそれらのフレームごとのマイクロトランスフォーム
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 = 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) — 垂直弧
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)

# 行2：running-left = running-rightのミラー
magick "${RUN_DIR}/cells/row1-strip.png" -flop -alpha set "${RUN_DIR}/cells/row2-strip.png"

マイクロトランスフォームテーブルはCodex Petに読めるが微妙なCodex内での動きを与えるものです。行ごとに数値を好みに合わせて調整してください。デルタは意図的に小さい（1-2ピクセル）ため、Codex Petは気になることなく生き生きした感じになります。

ステップ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をプロンプト — 機能するもの

単一のGPT Image 2呼び出しがすべてを決定します。このプロンプトを正しく取得すれば、残りは決定論的です。

キビプロポーション固定でリード。 「誇張されたキビプロポーション、頭は図身長の約60パーセント」は、背の高い細い文字（192x208セルに悪い柱状パッドボックスで適合）と頭が支配的なキビ（セルを自然に埋める）の違いです。後者はCodexの組み込みCodex Petのように見えます。

すべてのCodex Petベースプロンプトでマゼンタ#FF00FFクロマキーを明示的に要求。 GPT Image 2はRGBのみを出力します（アルファなし）。透明なCodex Petを取得する唯一の方法は、既知の背景色をポストプロセスで色除去することです。

ペット自体のクロマキーカラーを禁止。 追加：「ペット自体はクロマキーカラーまたはマゼンタに近いハイライトを使用してはいけません。」そうでない場合、クロマキーステップはマゼンタ風になるCodex Petボディパーツを削除します。

スタイルをピン。 「ピクセルアート系、太いシルエット、1-2ピクセルアウトライン、限定的なパレット、フラットなセルシェーディング」 — Codex PetをCodexハウススタイルと一致させるすべての用語をピンします。

間違ったスタイルを禁止。 「磨かれた図解なし、絵画的レンダリングなし、アニメキーアートなし、3Dレンダーなし、光沢のあるアプリアイコンなし、リアルな詳細なし。」これなしでは、GPT Image 2は過度にレンダリングされたアニメアートに引き付けられます。

アンチパターン：

• 一般的な「透明背景」 — GPT Image 2は近い白を塗ります。クロマキーを使用してください。
• モデルにプロポーションをフリースタイルさせる — 192x208に収まらない背の高い細いキビを描画します。
• 1つのプロンプトでスタイルを混ぜる — 1つのスタイルアンカーをピンして、それを守ってください。

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

ステップ3のデフォルトImageMagickレシピは、組み込みCodex Petに似たCodex Petアニメーション — 微妙なボブ、時折のまばたき、ジャンプ弧、頭の傾き — を生成します。アニメーションをより認識させたり、より認識させなくしたりするには、デルタを調整します：

• より大きなidle bob：行0のshift:0:-1をshift:0:-2に変更します。
• より速い走行サイクル：行1の水平シフトを増加させます（例：shift:2:-1の代わりにshift:3:0）。
• 高いジャンプ：行4のピークをshift:0:-8からshift:0:-12に変更します。
• review内の強い頭の傾き：rotate:-2 / rotate:2をrotate:-4 / rotate:4に変更します。

デルタを小さく（≤4ピクセルまたは≤4°）保つため、Codex Petは気になりません。

FAQ — Codex Pet

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

hatch-petの代わりにこのCodex Petスキルを使用する理由は？ 公式hatch-petはCodex内部の$imagegenシステムスキル（Codex Pro）が必要です。このスキルはRUNCOMFY_TOKENのみが必要で、RunComfy CLIを経由して同じアニメーション行仕様を実行し、合計で1回のGPT Image 2呼び出しです。

Codex Pet生成にはどのくらい時間がかかりますか？ 約2分 — 1回のGPT Image 2 edit呼び出し（約90秒）とImageMagickアトラスアセンブリの数秒。

1回のAPIですべてなのはなぜですか？ 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ピクセル。各行ストリップは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が正しく再生するためです。

制限事項

• Codex Petあたり1つの標準的なポーズ — アニメーションはImageMagickトランスフォーム経由であり、マルチフレームモデル生成ではありません。これは組み込みCodex Petの微妙なアニメーションと一致しますが、劇的なモーション（例：独特なフレーム単位の走行サイクル）を生成しません。
• GPT Image 2はアルファを出力しません — マゼンタクロマキー+ポストプロセスは回避策です。Codex Petにマゼンタに近い色がある場合（キビパレットでは珍しい）、プロンプトとポストプロセスの両方でクロマキーを別の固体（#00FFFFシアンまたは#00FF00緑）に切り替えます。
• 身元の逸脱 — GPT Image 2はソース画像の身元をCodex Petスタイルに簡略化する場合があります。特定の小さな機能（例：イヤリング、小道具の色）がシフトする場合があります。
• Codex Pet上のオーディオ／音声なし — Codex Petはビジュアルのみです。

終了コード

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

code	意味
0	Codex Pet標準的に正常に生成されました
64	不適切なCLIargs
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回呼び出し、マゼンタ上の1024x1024標準的なCodex Petを生成します。
2. ImageMagickはマゼンタをアルファ0にクロマキーし、スプライトbboxをトリムし、192x208セルにアスペクト適合させます。
3. ImageMagickはマイクロトランスフォーム（1-2ピクセル変換、まばたきマスク、回転、ミラー）を標準的なセルに適用して9つの行ストリップをプログラム的に構築します。
4. 9つの行ストリップは1536x1872 Codex Petアトラスにスタックされます。アトラスはWebPに変換されます。
5. pet.jsonマニフェストが書き込まれます。両方のファイルは${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置き換えではありません — 公式hatch-petはCodex Proが関係している場合に好ましいです。自己ホストされたGPT Image 2ではありません — 機能するRunComfyアカウントに依存します。

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

• トークンストレージ：runcomfy loginはAPIトークンを~/.config/runcomfy/token.jsonにモード0600で書き込みます。CIでファイルをバイパスするにはRUNCOMFY_TOKEN環境変数を設定してください。
• 入力境界：Codex Petプロンプトは--input経由でJSONとして渡されます。CLIはシェル展開を行いません。シェルインジェクションサーフェスなし。
• サードパーティコンテンツ：ソース画像URLはRunComfyサーバーによってフェッチされます。外部URLを信頼できないものとして扱う — 画像ベースのプロンプトインジェクションは画像編集モデルの既知のリスクです。
• アウトバウンドエンドポイント：model-api.runcomfy.netと*.runcomfy.net / *.runcomfy.comのみ。
• 生成ファイルサイズキャップ：CLIは単一Codex Pet標準的なダウンロード> 2GiBを中止します。
• ローカルインストールパス：最終Codex Petは${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/に書き込みます。リモートアップロードなし。