Codexペット機能を支える hatch-pet スキル徹底解剖——技術スタックと「他プロダクトへの流用」戦略

2026-05-03 （更新: 2026-07-03） by ZeroZawa

hatch-petが揺らした2026年GW——Codex Pet機能の正体

2026年5月2日、OpenAIが Codex app に投入した Pet機能は、Mac開発者の週末を奪いました。/pet でMacのデスクトップにアニメ仔獣を召喚し、Codex に $hatch-pet スキルをインストールした上で /hatch を叩けば自分だけのペットを生成できます（/hatch を有効化するには $hatch-pet の事前インストールが必要です）。9to5Macは「Lil Finder Guy が気がつけばFinderアイコンの上にいた」と書き、Engadgetは「ClippyのリメイクからSlackマスコットまで、ユーザは早速無限増殖を始めている」と報じました。

熱狂の正体は単なるかわいさではありません。Codex Pet はAIエージェントの「いま走っている／待ち受けている／レビュー待ち」という3状態を、アプリを切り替えることなく視界の隅で伝える Dynamic Island 風オーバーレイです。退役した Claude Code Buddy が ASCII 18種固定だったのに対し、Codex は画像生成スキル経由で自分のペットを無限に作れます——所有感と実用性を両立させたところに刺さるユーザが続出しました。

この記事では、Pet機能の中核である hatch-pet スキルを技術解剖し、Apache 2.0 ライセンスで何が許され何がリスクかを整理した上で、他のプロダクトへ流用するための具体策を5つ提示します。ただの紹介記事にせず、明日からあなたのプロダクトに組み込める設計図にまで落とし込みます。

hatch-petスキル全体図: 8×9アトラス・4ステージパイプライン・5活用路線

1. hatch-pet スキルの全体像——責務分離が綺麗な二層構造

hatch-pet は OpenAI 公式の openai/skills リポジトリ配下にあり、Apache License 2.0 で公開されています。ディレクトリ構成は次の通りです。

skills/.curated/hatch-pet/
├── SKILL.md              # フロー記述・Codex Agent向け指示書
├── LICENSE.txt           # Apache 2.0
├── agents/openai.yaml    # サブエージェント定義
├── references/
│   ├── animation-rows.md       # 9行アニメーション仕様
│   ├── codex-pet-contract.md   # pet.json と spritesheet 規約
│   └── qa-rubric.md            # 受け入れ基準
└── scripts/              # 14個のPythonスクリプト + 1個のシェルラッパー（決定論的処理）

スキルの設計思想を一言で言えば「生成は委譲し、合成は決定論で固める」です。視覚生成は $imagegen という別のシステムスキルへ完全に委譲し、hatch-pet 自身はプロンプト生成・マニフェスト管理・フレーム抽出・アトラス合成・QA・パッケージングだけを担います。Pillow ベースの Python スクリプト群が、生成画像を受け取った後の幾何学的処理に責任を持ちます。

この線引きは重要です。SKILL.md には次のような強い禁則が並びます。

「ローカルのPython/Pillow/SVG/canvas/HTML/CSS でペット視覚を生成・タイル・歪ませ・反転・合成してはならない」
「imagegen-jobs.json を手で書き換えて視覚ジョブを完了扱いにしてはならない」
「決定論的スクリプトは生成済み画像のみを処理してよい」

LLMエージェントが「画像生成APIが高い／重いから」と勝手にローカル合成へ逃げるのを防ぎ、生成と検証の責務を物理的に切り離しています。

hatch-petの二層構造アーキテクチャ: $imagegen委譲と決定論スクリプトの責務分離

2. Spritesheet Atlas 仕様——8列×9行に固定された動作辞書

Codex が読み込むペットアトラスは固定形状です。references/codex-pet-contract.md と references/animation-rows.md から読み取れる仕様を整理します。

アトラス幾何

フォーマット: PNG または WebP（透明背景）
解像度: 1536 × 1872 ピクセル
グリッド: 8列 × 9行
セル: 192 × 208 ピクセル
未使用セルは完全に透明

9行のアニメーション辞書

Row	State	Used columns	Frame durations
0	idle	0-5	280 / 110 / 110 / 140 / 140 / 320 ms
1	running-right	0-7	各120 ms、最終220 ms
2	running-left	0-7	各120 ms、最終220 ms
3	waving	0-3	各140 ms、最終280 ms
4	jumping	0-4	各140 ms、最終280 ms
5	failed	0-7	各140 ms、最終240 ms
6	waiting	0-5	各150 ms、最終260 ms
7	running	0-5	各120 ms、最終220 ms
8	review	0-5	各150 ms、最終280 ms

Webview側は CSS の background-position を行と列のインデックスから計算するだけでアニメーションが回ります。サーバ側もネイティブ側もこのアトラスさえ用意すれば、再生ロジックは数十行で済みます——非常にポータブルなコントラクトです。

配信パッケージ

最終出力は ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/ に配置する次の2ファイルだけ。

{
  "id": "pet-name",
  "displayName": "Pet Name",
  "description": "One short sentence.",
  "spritesheetPath": "spritesheet.webp"
}

pet.json と spritesheet.webp がフォルダに揃っていれば、Codex app は自動でロードします。プラグインインストーラも独自フォーマットも要りません、フォルダ規約だけで成立しているのが軽量で美しいところです。

3. パイプライン——base → row → mirror → finalize の4ステージ

hatch-petパイプライン4ステージのプロセスフロー図

実行フローは決定論スクリプトとサブエージェントの合奏で進みます。SKILL.md の Default Workflow を時系列で追います。

Stage 1: 準備（prepare_pet_run.py）

実行フォルダ・プロンプトファイル・imagegen-jobs.json マニフェストを生成します。同時に references/layout-guides/<state>.png という不可視の構成参照画像を9枚作り、各行の生成ジョブにレイアウト専用入力として添付します。これにより画像モデルにフレーム数・間隔・センタリング・余白を「形」で伝える設計です。生成された行ストリップにガイドの枠線や背景色が混入したら不合格——ガイドはあくまで構成参照であって描画対象ではありません。

Stage 2: 生成（$imagegen 委譲 + サブエージェント並列）

親エージェントがまず base ジョブを走らせ、record_imagegen_result.py でペットの canonical reference を確定します。以降の row ジョブは原則サブエージェントに並列委譲する規約です。SKILL.md は次のように明記しています。

The parent agent must own the manifest and package writes.（親エージェントはマニフェストとパッケージ書き込みを独占しなければならない）

サブエージェントは row プロンプト・入力画像パス・QA 判断基準を受け取り、選定済みの ig_*.png のパス1つだけを返します。record_imagegen_result.py を呼ぶのも decoded/ にコピーするのも親だけ——マニフェスト競合と来歴チェックの分散を防ぐ典型的なリーダー・フォロワー構成です。

Stage 3: ミラー派生による1ジョブ節約

running-right を承認した後で、ペットが視覚的に左右対称（向きに依存するロゴ・利き手の小道具・テキストがない）と判断できれば、derive_running_left_from_running_right.py で running-left を反転派生します。これで通常10ジョブのうち1ジョブを削減できます。非対称なら通常通り $imagegen で生成し直します——コストとアイデンティティ保存のトレードオフを明示的に切り替える設計です。

Stage 4: 検証とパッケージング（finalize_pet_run.py）

compose_atlas.py で個別フレームを 1536 × 1872 のアトラスへ合成し、validate_atlas.py が寸法・透明度・チャネル数を検証します。続けて make_contact_sheet.py がコンタクトシートPNGを、render_animation_videos.py が状態ごとのプレビューmp4を生成します。最後に package_custom_pet.py が pet.json と spritesheet.webp を pets ディレクトリに配置します。

ここで興味深いのが SKILL.md の次の文言です。

Treat visual identity drift as a blocker even when qa/review.json and final/validation.json have no errors.

決定論的検証が通っても、コンタクトシートを目視してアイデンティティがブレていたら不合格にしろ、と書かれています。寸法・透明度・フレーム数といった機械検証では捕まらない「同じ生き物に見えるか」を、人間（あるいはレビュー担当エージェント）の責務として明確化しています。AI生成パイプラインの最終ゲートとして参考になります。

4. 実走検証——パイプラインを実際に動かしてみました

ここまでの解剖はドキュメントと SKILL.md の記述に基づくものでした。ここからは実際にリポジトリを clone し、パイプラインを手元で走らせて確認した一次情報です。

方法: github.com/openai/skills を clone し、本記事の pubDate（2026-05-03）に対応するスナップショット commit af9b54f2（2026-05-01, “add hatch skill #384”）を pin しました。venv + Pillow 12.3.0 の環境で skills/.curated/hatch-pet/scripts/ を直接実行し、画像生成 API キーは一切使わず、各スクリプトが備える非公開のテストモードフラグ（--allow-synthetic-test-source など）でパイプラインの幾何学的処理だけを検証しています。実際の画像生成の品質を検証したわけではなく、hatch-pet が主張する決定論パイプラインの機構を検証する実験である、と先に断っておきます。

実行した流れは次の通りです。

prepare_pet_run.py --pet-name TestPet ... --force → imagegen-jobs.json（10ジョブ = base 1 + row 9）と、9枚のレイアウトガイド PNG を生成。記事が説明する「不可視の構成参照画像」の実物を確認しました。
record_imagegen_result.py --allow-synthetic-test-source を base 含む9回実行し、全て ok: true を確認しました。
derive_running_left_from_running_right.py --confirm-appropriate-mirror → ok: true、derived_from: "running-right"。Stage 3 のミラー派生の主張を実機で確認しました。
finalize_pet_run.py --allow-synthetic-test-sources --skip-videos が内部で以下を順に orchestrate することを確認しました。
- extract_strip_frames.py（method=auto）は、chroma key が一致すると「components」（連結成分抽出）方式を選びました。単純な等幅スライスではありません。
- inspect_frames.py --require-components は、1回目はわざと chroma key をミスマッチさせた状態で実行し、9行すべてで「used extraction method slots; regenerate the row」と正しく reject されることを確認しました。QA ゲートはお飾りではなく実際に機能しています。chroma key を修正して再実行すると ok: true, errors: [] で通過しました。
- compose_atlas.py が spritesheet.png / spritesheet.webp を実際に合成し、PIL で開いて 1536 × 1872 RGBA であることを確認しました（記事の主張と一致）。
- validate_atlas.py は ok: true、errors/warnings ともに0件でした。
- make_contact_sheet.py がコンタクトシートPNGを生成しました。
- package_custom_pet.py が書き出した pet.json のフィールドは、記事が説明した {id, displayName, description, spritesheetPath} のスキーマと完全一致しました。

正直に書いておくべき限界もあります。render_animation_videos.py は今回の検証環境に ffmpeg が入っておらず FileNotFoundError で失敗し、実行では検証できていません。ソースコードを読んだ限り、行ごとに ffmpeg を呼び出しループ用GIF/MP4を生成する実装で記事の説明と矛盾しませんが、これはソースコードの確認にとどまります。また、テストモードフラグを使ったため、実際の $imagegen による画像生成そのもの（プロンプトの質・生成画像の忠実度）は今回の検証対象外です。今回の実走が確認できたのは、あくまで「決定論スクリプト群が主張通りに動くか」という機構部分だけだと理解してください。

追記（2026-07-03）——上流は9日後に全面刷新されていました

今回の実走検証で openai/skills の commit 履歴を追いました。記事が解剖した af9b54f2（2026-05-01）は、わずか9日後の commit c25113b（2026-05-12, “Replace hatch-pet curated skill workflow #399”）で全面的に置き換えられていたことが分かりました。

$ git log --oneline --follow -- skills/.curated/hatch-pet
c25113b 2026-05-12 Replace hatch-pet curated skill workflow (#399)
f253260 2026-05-06 Improve hatch-pet search metadata (#392)
dbb7d19 2026-05-05 Clarify hatch-pet running row semantics (#391)
af9b54f 2026-05-01 add hatch skill (#384)   <- 本記事が解剖したスナップショット

c25113b の diffstat を確認すると、finalize_pet_run.py / generate_pet_images.py / package_custom_pet.py / pet_job_status.py / queue_pet_repairs.py / record_imagegen_result.py の6スクリプトと render_animation_videos.sh シェルラッパーが削除され、render_animation_videos.py は render_animation_previews.py へリネームされていました。トリアージ時点（2026-06-23, HEAD 49f948fa）で現存するのは8スクリプトのみで、シェルラッパーは消滅しています。SKILL.md も320行から539行に増え、サブエージェント/ブランド探索/スタイルプリセットという別ワークフローに再設計されていました。

つまり本記事が「14個のPythonスクリプト+1個のシェルラッパー」と説明している構造は、2026-05-01時点のスナップショット限定の記述であり、現在の openai/skills HEAD では当てはまりません。記事本文の記述はスナップショット時点の解剖として正確なため訂正はせず、上流を追跡する読者のためにこの一次情報だけをここに追記します。

5. 透明背景を保つための「効果禁則」

Webview側でアトラスを CSS で重ねる以上、各セルは clean な chroma-key 除去ができないと困ります。SKILL.md は禁則を異常なほど細かく書いています。

許される効果は「ペットのシルエットに物理的に触れている」「フレームスロットを越えない」「ピクセル調で不透明」「chroma-key 隣接色を使わない」のすべてを満たすものだけ。具体的には涙・煙・星などをペットと重ねる場合に限って許可されます。

逆に禁止されるのは——モーションブラー、スピードライン、残像、影（ドロップ・コンタクト・楕円床影）、グロー、オーラ、ハロ、衝撃エフェクト、宙に浮いたスパークル、テキスト、フキダシ、UIパネル、コードスニペット、市松透明、白背景、黒背景。

waving: show the wave through paw pose only.（手を振る動作は前足のポーズだけで表現せよ） jumping: show vertical motion through body position only.（ジャンプは体の高さだけで表現せよ）

凡庸なプロンプト設計だと「振っている感」を出すために波線や輝きを描かせてしまいますが、それは透明背景処理を破壊します。hatch-pet はこの落とし穴を網羅的に列挙し、生成プロンプトに必ず含めることで、ピクセルレベルの清潔さを担保しています。

6. ライセンスの境界——どこまで持ち出せて、何が残るか

hatch-pet/LICENSE.txt は Apache License 2.0。商用利用OK、改変OK、派生OK、特許防衛条項あり、コピーレフトなし。スキル本体（SKILL.md・Pythonスクリプト・YAML定義・参考ドキュメント）はそのまま再配布・派生可能です。

ただし注意すべき分離線が3つあります。

1. 生成画像の権利は別

$imagegen は OpenAI の画像生成API（gpt-image-2 など）に依存します。生成された画像の利用条件は OpenAI の API 利用規約に従います。スキルのコードは持ち出せても、出力画像の取り扱いはモデル提供元のルールに支配されます。

2. Codex 内蔵ペット画像は別ライセンスの可能性

Dewey、Fireball、Rocky、BSOD などの built-in ペット画像は OpenAI が独自に制作・配布するアセットで、Apache 2.0 でリポジトリに含まれているとは限りません。コードは流用、内蔵ペット画像は流用しない、が安全側です。

3. `$imagegen` システムスキル本体の扱い

SKILL.md は ${CODEX_HOME}/skills/.system/imagegen/SKILL.md を参照すると書いています。実はこの .system/imagegen も openai/skills リポジトリ配下に含まれています。同じ Apache 2.0 ライセンスで、Codex 同梱で自動インストールされる仕組みです。コードそのものは流用できます。ただし内部では OpenAI 画像生成 API（gpt-image-2 など）を呼び出すラッパーです。Codex 外のプロダクトに移植する場合は、$imagegen 呼び出し部を別の画像生成プロバイダ（fal.ai / Replicate / Stable Diffusion API / 自前推論）へ差し替える前提で設計するのが現実的です。

要約すると、hatch-pet の決定論的スクリプト群と Spritesheet コントラクトは丸ごと自分のものにできます。差し替えるべきは画像生成の呼び口だけ。これはリスクの低い派生路線になります。

7. これを使った新プロダクト——5つの具体的な活路

ここからが本題です。「Codex Pet すごいね」で終わらせず、hatch-pet の設計を借りて何を作るかを5案出します。いずれも Spritesheet Atlas + 状態マッピングという共通基盤で動きます。

A. CI/CD ステータスペット（DevOps SaaS）

GitHub Actions・CircleCI・GitLab CI の実行状態をブラウザのフローティングウィジェットで表示します。queued → idle、running → running-right、success → waving、failed → failed、approval-required → review といった状態マッピングを定義し、開発チームが自社マスコットや言語ロゴから hatch-pet フォークでペットを生成します。dashboard をフルスクリーンで開かなくても、視界の隅で「ビルド待ち」が分かります。Slack 通知の心理的負債を1段下げられます。

B. 長時間バッチ・クエリ実行モニタ（DBA・データエンジニア）

Airflow・dbt・Snowflake の長時間クエリやDAG実行に対し、30秒を超えたら waiting ペットがデスクトップに出現します。完了で waving、失敗で failed、ロック競合で review。DBA文化のマスコット（PostgresのZou、RedisのキューブMC）から派生ペットを大量生成し、社内インフラの「待ち時間」をエンタメ化します。コマンドラインのプログレスバーより遥かに記憶に残ります。

C. ライブ配信用 OBS Overlay

ストリーマー本人モチーフのペットを hatch-pet で生成し、OBSのブラウザソースとして埋め込みます。録画中 → running、コメント未読 → review、スパチャ受信 → jumping、配信終了直前 → waiting 等、9行のアニメーション辞書を配信状態へマッピングし直します。Spritesheet 仕様は変更不要、状態マッピング層を Twitch/YouTube Live API に繋ぐだけ。

D. SaaS の「待ち時間」UX 改善キット

重いAPI処理・ファイルアップロード・AI推論の待機画面で、製品マスコットのアニメを再生します。スピナーの代わりに親しみやすいペットが「思考中」「もうすぐ完了」を表現します。ローダーをペットに置き換えるだけで、平均待機時間の体感を有意に削減できることはローダーUX研究で何度も実証されています。hatch-pet の Atlas 仕様と CSS 再生コードを SaaS テンプレートとして配るだけで、共通UX資産になります。

E. 教育プラットフォームの学習コンパニオン

DuolingoやMonacaのような教育プラットフォームで、ユーザの進捗をペットの動作にマップします。連続学習中 → running、新トピック解放 → jumping、誤答 → failed、復習タイム → review、目標達成 → waving。子ども向けプラットフォームほど刺さりますし、ユーザに自分のペットを hatch させる機能はそのまま課金フックになります（ChatGPT Pro 30日無料の誘引と同じ構造です）。

8. MVP 設計図——明日から動かす最小構成

5案のいずれを取るにせよ、初手は同じです。hatch-pet をフォークし、画像生成の口を差し替え、状態マッピング層だけを自前で書きます。

流用するもの

scripts/compose_atlas.py      # アトラス合成（PIL）
scripts/extract_strip_frames.py # 行ストリップ→個別フレーム
scripts/validate_atlas.py     # 寸法・透明度検証
scripts/make_contact_sheet.py # QAコンタクトシート
references/animation-rows.md  # 9行仕様（流用 or 再定義）
references/codex-pet-contract.md # pet.json 規約（差し替え可）

差し替えるもの

$imagegen 呼び出し部分 → fal.ai / Replicate / 自前推論 API
pet.json スキーマ      → 自社プロダクト用に拡張（状態マッピング情報を追加）
state mapping 層       → ドメインイベント（CI状態・配信状態・学習進捗）と row index の対応表

実装ステップ

hatch-pet を Apache 2.0 表記を残してフォーク
scripts/generate_pet_images.py を自社の画像生成プロバイダ向けに書き換える（インターフェイスは --run-dir --states all のまま）
MVP 段階では built-in ペット1〜2種類だけを同梱、/hatch 相当のセルフ生成は v2 に回す
Webview 側に <PetWidget> を実装。CSS の background-position を 192px×208px グリッドで切り替える数十行のコンポーネントで足りる
状態イベントの WebSocket / Server-Sent Events を購読し、row index を更新するだけで完成

この構成なら、ペット生成パイプラインに踏み込まずに既存の Codex 公式ペット2〜3種類だけで MVP を出して反応を見ることすら可能です（ただし内蔵画像のライセンスは要確認）。動いてからユーザに自作ペット機能を解放する流れがリスク最小になります。

9. 落とし穴と現実的な制約

設計が綺麗でも、運用に持ち込むとコストとリスクが見えてきます。

生成コスト: 1ペット作成で約10回の画像生成ジョブが走ります。gpt-image-2 の単価で換算すると数百円〜千円台のオーダー。ユーザが軽率に /hatch を連打する設計は破綻します。レート制限・プレビューモード・モデレーション必須。
アイデンティティ一貫性: 9行を別ジョブで生成すると微妙にデザインがブレます。決定論的検証では捕まらないため、コンタクトシート目視レビューが最後のゲートになります。これを自動化したいなら、CLIP類似度や DINO embedding を使った独自レビュー層を追加することになります。
ライセンス境界の二重管理: コードは Apache 2.0、生成画像はモデルプロバイダ規約、内蔵画像は別ライセンスの可能性——3層の権利関係をユーザにも伝える必要があります。
$imagegen 依存の罠: SKILL.md は $imagegen のCLIフォールバック挙動まで委ねています。完全互換の差し替え APIを用意するのは初手のコストが高いです。最初は Replicate 等の gpt-image-2 互換プロキシで MVP を作るのが現実解。

10. 結論——ペットは UX の触覚レイヤー

Codex Pet が示したのは「AIエージェントの状態を感じるUI」という第三のフロンティアです。プログレスバーは脳に届くが心には届かない、ログ通知はノイズに紛れる、Slack は読み逃します。ペットは視界の隅に常駐し、状態を表情と動作で伝える——ビジュアルとも音声とも違う、触覚に近いインフォメーションチャネル。

そして hatch-pet は、その新しいレイヤーを自分のプロダクトに移植可能な形で公開した数少ない実例です。Spritesheet コントラクトと決定論パイプラインさえ借りれば、CI/CD・配信・SaaS・教育、どこにでも刺さる「状態の触覚化」コンポーネントを2週間で MVP化できます。

あなたのプロダクトの「待ち時間」と「成功の瞬間」を、ペットに任せてみる価値はあるでしょうか。Codex の Pet 機能は、「実用一辺倒のSaaSに感情の余白を入れる」のは2026年のUX文法の一つになるかもしれない、というシグナルを発しています。