Codexアプリに、作業の進捗をデスクトップ上で知らせる「ペット」という小さなデジタルマスコット（コンパニオン）ができました。ペットは単なる静止画ではなく、待機、移動、ジャンプ、失敗時のリアクション、レビュー中の仕草など、複数の状態に応じて動きます。

この記事では、独自のペットを孵化させるためのhatch-petスキルを紹介します[1]。コンセプトや参考画像から、Codexアプリで読み込めるpet.jsonとspritesheet.webpを作るまでの流れを、内部処理も含めて見ていきます。

Codexアプリのペットとは

ペットは、Codexアプリの動作状況を教えてくれる小さなアニメーションキャラクターです。

まず実際に動いている様子を見てみます。次の動画は、この記事のサンプルとして猫の写真から作成したTuxというペットの待機アニメーションです。

静止画として見ると、ペットは次のような小さなスプライトです。

ペットは、1枚の静止画ではなく、スプライトシートとして用意します。Codexアプリは、そこに並んだ小さな絵の表示位置を切り替えることで、待機、移動、手を振る、失敗時の反応などをアニメーションとして見せます。

hatch-petは、この一連の作業を支援するスキルです。見た目の生成には画像生成を使い、フレーム配置や検証、パッケージングのように再現性が必要な処理はスクリプトで進めます。

ペットの基本仕様

Codexアプリのペットは、固定サイズのスプライトアトラス（一つの画像にキャラクターの動きの各コマを並べた形式）で構成されています。

実際のアトラスは、横に8セル、縦に9行のマス目です。1つのセルが1フレーム、1つの行が1種類の動きに対応します。たとえば、1行目はidle、2行目はrunning-rightのように、行ごとに役割が決まっています。

次のコンタクトシートを見ると、セルと行の関係がつかみやすくなります。これは確認用に生成した画像で、実際にアプリへ読み込ませるスプライトシートには行名やセル番号は入りません。

• アトラス全体：1536×1872px
• グリッド：8列×9行
• 1セル：192×208px
• 背景：透明
• 最終出力：PNGまたはWebP
• カスタムペットの構成：pet.jsonとspritesheet.webp

ある行で6フレームしか使わない場合でも、残りのセルは完全に透明にします。セルの外にはみ出した影、エフェクト、背景、ガイド線も入れません。

ペットが持つ9種類のアニメーション状態

hatch-petが扱うペットは、9行のアニメーション状態を持ちます。各行で使うセルの範囲はスキル側で規定されています。セル番号は左から0〜7です。

• 行0：idle：使用セルは0〜5です。通常待機、呼吸、まばたきのための行です。
• 行1：running-right：使用セルは0〜7です。右方向への移動を表します。
• 行2：running-left：使用セルは0〜7です。左方向への移動を表します。
• 行3：waving：使用セルは0〜3です。手を振る、挨拶するなどの動きを表します。
• 行4：jumping：使用セルは0〜4です。予備動作、上昇、着地までのジャンプを表します。
• 行5：failed：使用セルは0〜7です。失敗、エラー、しょんぼりした反応を表します。
• 行6：waiting：使用セルは0〜5です。待機中の別バリエーションを表します。
• 行7：running：使用セルは0〜5です。正面またはその場走りを表します。
• 行8：review：使用セルは0〜5です。レビュー中、考え中、注視している状態を表します。

各行の役割に合わせて、ポーズや表情の変化を作ります。

hatch-petスキルが担う範囲

hatch-petは、Codex互換のペットを作るための制作パイプラインです。大きく分けると、次の作業を扱います。

• ペット名、説明、参考画像、スタイル条件の整理
• ベース画像の生成
• 各アニメーション行のプロンプト作成
• 画像生成ジョブの管理
• 生成結果の記録
• 行画像（各アニメーション行の画像）からのフレーム抽出
• 8列×9行のアトラス合成
• 検証結果、コンタクトシート、プレビュー動画の生成
• pet.jsonとspritesheet.webpのパッケージ化
• 失敗した行だけを対象にした修復

見た目やポーズの生成には画像生成を使い、生成結果の記録、セル配置、未使用セルの透明化、スプライトシートの検証などはスクリプトで行います。

制作フロー⁠：ペットが“孵る”まで

hatch-petでペットを作る基本的な流れは、次の4段階です。

1. 制作条件の準備
2. メインの見た目の生成
3. 各ポーズの生成
4. スプライトシート化とパッケージング

1. 制作条件の準備

最初に、ペットの基本情報と制作条件を決めます。この段階で行うのは、画像生成そのものではなく、hatch-petが後続の生成や検証に使う条件の整理です。

• ペット名
• 短い説明
• 見た目のコンセプト
• 参考画像の有無
• スタイル上の制約
• 実行フォルダ

テキストだけで作る場合は見た目のコンセプトを伝え、参考画像がある場合は画像を添付します。依頼文の例は後述します。

2. メインの見た目の生成

次に、ペットのベース画像を生成します。ベース画像は、以降のアニメーション行を生成するときの基準です。

参考画像がある場合でも、hatch-petではまずベース画像を作ります。これは、参考画像をそのまま各行に使うのではなく、Codexペットとして適したベース画像を作るためです。以降のidle、running-right、wavingなどは、このベース画像と同じキャラクターに見える必要があります。

この段階で、キャラクターのシルエット、顔、配色、持ち物、輪郭線の太さを確認しておきます。

3. 各ポーズの生成

ベース画像が決まったら、9種類のアニメーション行を作ります。hatch-petの通常フローでは、ベース画像を記録したあと、各行の画像生成をサブエージェントに分担します。

hatch-petでは、最初にidleとrunning-rightを重視します。idleはペットの基本状態であり、モーションを減らす設定でも使いやすい必要があります。running-rightは、移動時のシルエットや足運びを確認するための重要な行です。

running-leftは、場合によってはrunning-rightを左右反転して作れます。ただし、片側だけの模様、片手に持った道具、読める文字やロゴ、左右非対称のアクセサリーなどがある場合は、単純な反転で意味が変わる可能性があります。見た目が左右対称で、反転しても意味や同一性が壊れない場合だけ、ミラー処理を使います。

4. スプライトシート化とパッケージング

すべての行画像がそろったら、行画像からフレームを抽出し、9行8列のアトラスに合成します。

最終的なカスタムペットは、通常${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/に保存されます。中身はpet.jsonとspritesheet.webpです。

pet.jsonには、ペットのID、表示名、説明、スプライトシートのパスが入ります。spritesheet.webpは、Codexアプリが実際に表示に使う画像です。

サンプル⁠：猫の写真からペットを孵化させる

ここまでの流れを、実際の参考画像で見てみます。今回は、白黒の猫の写真をもとに、TuxというCodexペットを作成しました。Tuxは、白黒のタキシード柄の猫から付けた短い名前です。

この写真をそのまま小さなスプライトにすると、毛並み、背景、影、地面の情報が多すぎます。そこで、Codexは次のような方針でベースペットを作りました[3]。

• 黒い頭と背中、白い鼻筋、白い胸元、白い足を残す
• 大きな黄色い目を特徴として扱う
• 写実的な毛並みではなく、少ない色数と太い輪郭線で表現する
• 背景、草、地面、影、文字、浮いたエフェクトを入れない
• 192×208pxのセルでもわかる、丸いちびキャラ風のシルエット

冒頭に示したベースペットでは、写真の細かな毛並みや背景は省略し、黒白模様、黄色い目、白い鼻筋と胸元を、Codexペットとして判別しやすい形に整理しています。

このベース画像を基準に、idle、running-right、waving、failed、reviewなどの行を生成します。実行時には、idleとrunning-rightを先にサブエージェントへ分担し、同じ猫として見えるかを確認しました。running-leftについては、今回のTuxには文字、ロゴ、片手持ちの道具、左右で意味が変わるアクセサリーがないため、running-rightを目視確認したうえでミラー派生しました。

生成後は、前述のコンタクトシートで各アニメーション行を確認します。idle、running-right、running-left、waving、jumping、failed、waiting、running、reviewの各行で、同じ猫として見えるか、セルからはみ出していないか、余計な背景やエフェクトが残っていないかを見ます。

動きの確認には、各行から生成したプレビュー動画も使えます。冒頭で見たidleに加えて、running-rightでは右向きの足運び、failedではしょんぼりしたリアクションを確認します。

このサンプルでは、qa/review.jsonとfinal/validation.jsonのどちらもエラーなしでした。最終的なスプライトシートは1536×1872pxのRGBA画像として生成され、未使用セルは透明になっています。

内部処理⁠：画像生成と再現性が必要な後処理を分ける設計

hatch-petの特徴は、画像生成と再現性が必要な後処理を分ける設計を分けている点です。

画像生成が担当するもの

画像生成が担当するのは、主に見た目の創造性が必要な部分です。

• ベース画像
• idleなどの行画像
• running-rightなどの動きのバリエーション
• 失敗時やレビュー中の表情・ポーズ

行画像を生成するときは、ベース画像や参考画像を入力として使い、キャラクターの同一性を保つことを重視します。行ごとに別のキャラクターに見えてしまうと、スプライトシートとしては成立しても、ペットとしての一体感が失われます。

ベース画像はテキストだけで生成できますが、各アニメーション行はベース画像や参考画像を添えて生成します。また、各行にはレイアウトガイドが用意されます。これは、フレーム数、間隔、中央寄せ、安全な余白をモデルに伝えるための補助画像です。ただし、生成結果にガイドの線、枠、色、ラベルが見えてはいけません。ガイドはあくまで構図の参照であり、出力物の一部ではありません。

スクリプトが担当するもの

一方で、再現性が必要な処理はスクリプトが担当します。

• 実行フォルダの作成
• ペット設定ファイルの作成
• 画像生成ジョブのマニフェスト作成
• 生成結果の記録
• 行画像からのフレーム抽出
• フレーム検査
• アトラス合成
• 最終アトラスの検証
• QA用コンタクトシートの生成
• アニメーションプレビュー動画の生成
• カスタムペットのパッケージ化

この分担により、見た目の生成と、スプライトシートのサイズ、セル配置、未使用セルの透明化、パッケージ構造のような要件を分けて扱えます。ここでの「決定的な後処理」とは、同じ入力から同じ構造の成果物を作るための処理です。

内部で使われる主なスクリプト

hatch-petには、ペット制作を段階的に進めるためのスクリプトが用意されています。この記事ではコマンドの詳細には踏み込みませんが、主な役割は次のとおりです。

• prepare_pet_run.py：実行フォルダ、ペット設定、プロンプト、画像生成ジョブのマニフェストを準備する
• pet_job_status.py：次に実行できる画像生成ジョブを確認する
• record_imagegen_result.py：採用した画像生成結果をジョブにひも付けて記録する
• derive_running_left_from_running_right.py：条件が合う場合に、running-rightからrunning-leftをミラー派生する
• finalize_pet_run.py：フレーム抽出、アトラス合成、検証、QAメディア生成、パッケージ化を進める

生成画像を手で置き換えて完了扱いにするのではなく、採用結果やミラー判断を記録しながら進めます。これにより、後続のフレーム抽出やQAが同じ前提で動きます。

行生成を分担するサブエージェント

前述のとおり、hatch-petでは、ベース画像を記録したあと、各アニメーション行の画像生成をサブエージェントに分担する設計になっています。

親エージェントは、実行フォルダ、マニフェスト、採用結果、最終パッケージを管理します。サブエージェントは、指定された1つの行について画像生成を行い、生成された候補を確認して、採用する画像と短いQAメモを親エージェントに返します。

この分担には、次の狙いがあります。

• 複数の行生成を並行して進められる
• 親エージェントがマニフェスト更新を一元管理できる
• 行ごとの生成とQA観点を明確にできる
• imagegen-jobs.jsonの競合更新を避けられる

サブエージェントは、マニフェストを書き換えたり、生成画像をdecoded/にコピーしたり、最終化処理を実行したりしません。これらは親エージェントが担当します。画像生成の並列化と、制作状態の一元管理を両立するための分担です。

実行中に作られる主なファイル

hatch-petの実行中には、作業用フォルダに次のようなファイルが作られます。

run/
  pet_request.json #ペット名、説明、スタイル、参照情報などを記録
  imagegen-jobs.json #画像生成ジョブの状態を管理
  prompts/ #ベース画像や各行用のプロンプトを保存
  decoded/ #採用された生成画像を保存
  frames/frames-manifest.json #抽出されたフレーム情報を記録
  final/spritesheet.png #最終アトラスのPNG版
  final/spritesheet.webp #最終アトラスのWebP版
  final/validation.json #アトラス検証の結果
  qa/contact-sheet.png #全フレームを一覧で確認するための画像
  qa/review.json #QA結果を記録
  qa/run-summary.json #実行のサマリーを記録
  qa/videos/*.mp4 #各アニメーションのプレビュー動画

hatch-petは、画像生成だけでなく、制作管理と検証まで含めたワークフローとして動きます。

依頼文に含める情報

hatch-petでは、ペット名、説明、見た目、スタイル上の条件、参考画像の有無をもとに実行内容を準備します。依頼文として書くなら、次のように必要な情報をまとめておくと伝わりやすくなります。

テキストから作る場合

hatch-petでCodex用のペットを作ってください。

名前：Dewdrop
説明：水滴のような形をした、落ち着いた小さなペット

見た目：
- 水滴型のシンプルな体
- 青系の少ない色数
- 小さな黒い目
- 太めの暗い輪郭線
- ちびキャラ風
- 192×208pxのセルでもわかるシルエット

動きの希望：
- idleではゆっくりまばたきする
- wavingでは小さな手を上げる
- failedでは少ししぼんだ表情にする
- reviewでは前のめりに覗き込む

避けたいもの：
- 背景
- 床の影
- スピード線
- 波線
- 文字
- 浮いた星や記号
- 細かすぎる装飾

参考画像から作る場合

添付画像を参考に、Codex用のペットを作ってください。

条件：
- 元キャラクターの雰囲気は残す
- ただし、Codexのデジタルペット風に簡略化する
- 192×208pxのセルでもわかりやすい形にする
- 太い輪郭線と少ない色数にする
- 顔、配色、特徴的なシルエットは維持する
- 背景、文字、床の影、浮いたエフェクトは入れない

修復を依頼する場合

このhatch-pet実行結果を確認し、失敗している行だけ修復してください。
特に、running-left、waving、failedの見た目と透明背景を確認してください。

修復を依頼するときは、問題のある行と確認観点を短く伝えます。全体を作り直す必要がない場合は、対象行だけを直す前提にします。

デザイン上の制約

hatch-petでは、Codexアプリの組み込みペットに近い、デジタルペット風の見た目を基本にします。

基本は、太めの輪郭線、少ない色数、シンプルな表情、小さくてもわかるシルエットです。逆に、写実的な質感、3D風のレンダリング、複雑な装飾、ソフトなグラデーション、影やスピード線、文字やUIのような要素は避けます。

たとえばwavingでは、波線や記号ではなく、前足のポーズで手を振る動きを表現します。running系の行でも、スピード線や土ぼこりではなく、体と足の動きで走っていることを表します。

確認と修復で見るファイル

完成後は、生成されたQAファイルを見ながら確認します。自動検証の結果と、見た目の確認を分けて見ます。

• qa/contact-sheet.png：すべての行で同じキャラクターに見えるか、余計な背景やエフェクトがないか
• qa/videos/*.mp4：各状態の動きが自然か、idleやfailedなどの状態差がわかるか
• qa/review.json：フレーム抽出や行ごとのQAでエラーが出ていないか
• final/validation.json：アトラスサイズ、透明セル、使用セルなどに問題がないか
• final/spritesheet.webp：Codexに読み込ませる最終スプライトシート

問題が見つかった場合は、失敗した範囲だけを修復します。failedだけに余計な表現が入った場合はfailed行、running-leftだけが不自然な場合はrunning-left行を直します。全体を作り直すのは、ベース画像や全体の設計が大きく崩れている場合です。

孵化させたペットを使う

ペットのパッケージができたら、Codexの設定画面から選択します。カスタムペットとして読み込まれていれば、設定画面のペット一覧に表示され、Tuxのように選択できます。手動で配置する場合は、Codexのカスタムペット用フォルダに、pet.jsonとspritesheet.webpを置きます。Windows環境では、C:\Users\<user-name>\.codex\pets\<pet-name>\といったパスになります。