はじめまして、ますみです！
株式会社Galirage（ガリレージ）というAIスタートアップで、代表をしております^^
その他にも、「AIとコミュニケーションする技術（インプレス出版）」という書籍を執筆させていただいたり、生成AIアカデミーというYouTubeチャンネルを運営したり、上智大学で非常勤講師をしたりしています！
Codexに自分だけの「ペット」を住まわせると、開発体験が少しだけ楽しくなります。
Codexを長く使っていると、画面の中に小さな相棒がいるだけで、作業の手触りが変わるものです。
今回は、Codex Appで使える カスタムペット を、自分のフォルダに置いた2ファイルだけで動かす方法を紹介します。
例として、狼のキャラクターをベースにペットを作りました。
ここでは、 「Galirage Wolf」 と名付けています。
完成イメージは、9種類の状態（idle、running、waving、jumping ほか）を持つ小さなアニメーションです。
Galirage WolfのQA（Quality Assurance：品質確認）用コンタクトシート（Contact Sheet：全フレームを一覧表示した確認画像）
この記事のゴールは、~/.codex/pets/（Codex Appがカスタムペットを読み込むローカルフォルダ）に置いた2ファイルだけで、9つの状態を持つペットを画面に住まわせることです。
そこに到達するため、次の4ブロックを順番に見ていきます。
- 完成形 ：ペットを構成する2つのファイル（What）
- 仕様 ：8列 × 9行・1536 × 1872 ピクセルの制約（Spec）
- 実装 ：hatch-petで作る6ステップ（How）
- 振り返り ：QAで見るポイントと、作って分かったコツ（Lessons）
① 完成形：~/.codex/pets/ で動かす2つのファイル
ここからは、最終的に手元に置く成果物の形を見ていきます。
Codexペットは、~/.codex/pets/{ペット名}/ 配下の2ファイルだけで動きます。
pet.json と spritesheet.webp の役割分担
galirage-wolf/
├── pet.json
└── spritesheet.webp
役割分担は次のとおりです。
| ファイル | 役割 |
|---|---|
pet.json |
ペットの名前、ID、説明を持つマニフェスト（Manifest：定義情報をまとめた設定ファイル） |
spritesheet.webp |
全アニメーション状態を1枚に束ねたスプライト（Sprite：1キャラ分のコマ画像）シート |
pet.json の中身
今回の pet.json は、次の形にしました。
{
"id": "galirage-wolf",
"displayName": "Galirage Wolf",
"description": "A calm, intelligent pixel wolf companion for AI-native work.",
"spritesheetPath": "spritesheet.webp"
}
spritesheetPath は、同じフォルダ内のスプライトシートのファイル名を指します。
Codex App にペットを認識させる
この2ファイルを ~/.codex/pets/galirage-wolf/ に配置すれば、Codex Appから選べるようになります。
~/.codex/pets/galirage-wolf/
├── pet.json
└── spritesheet.webp
設定画面では、日本語UIなら 「設定 > 外観 > ペット」 、英語UIなら Settings > Appearance > Pets から選択できます。
設定画面の外観セクション下部にペット欄がある
ペット欄を開くと、Codex、Dewey、Fireballなどの標準ペットが並びます。
さらに下にスクロールすると、~/.codex/pets に置いたカスタムペットが表示されます。
標準ペット一覧の下にカスタムペットが表示される
設定に出てこない場合は、Codex Appを再起動すると反映されることがあります。
なお、Codex App の設定画面の全体像は、OpenAI公式の Codex settings も参考になります。
② スプライトの仕様：8列 × 9行・1536 × 1872
ここまでで、できあがる2ファイルの形を見ました。
次は、その中身を作る前に守るべき スプライトの仕様 を確認します。
Codexペットで一番大事なのは、かわいい絵を作ることだけではなく、Codexが読み取れる仕様に合わせることだからです。
画像サイズとグリッドの数値仕様
今回のペットでは、次の仕様に合わせました。
| 項目 | 値 |
|---|---|
| 画像形式 | PNG または WebP |
| 画像サイズ | 1536 × 1872 |
| グリッド | 8列 × 9行 |
| 1セル | 192 × 208 |
| 背景 | 透明 |
| 未使用セル | 完全に透明 |
サイズの内訳は、 横8セル × 縦9行 = 72コマ 。
1コマ 192 × 208 ピクセルが、Codex上で表示されるペット1コマぶんの単位です。
実際のスプライトシートは、次のようになります。
記事上では大きく見えますが、アプリ上では各セルが小さなペットとして表示されます。
8列9行のアトラス（Atlas：複数フレームを1枚に詰めた画像。spritesheet と同義）として構成した最終形
9つの状態（行）と役割
スプライトシートの9行は、それぞれ Codex 上での状態に対応しています。
| 行 | state | フレーム数 | 役割 |
|---|---|---|---|
| 0 | idle |
6 | 通常時の呼吸やまばたき |
| 1 | running-right |
8 | 右方向への移動 |
| 2 | running-left |
8 | 左方向への移動 |
| 3 | waving |
4 | あいさつ |
| 4 | jumping |
5 | 跳ねる反応 |
| 5 | failed |
8 | 失敗時のしょんぼり反応 |
| 6 | waiting |
6 | 待機中の小さな揺れ |
| 7 | running |
6 | 作業中のループ |
| 8 | review |
6 | 確認中・レビュー中の集中ループ |
紛らわしい3つの running の違い
ここで紛らわしいのが、running-right ・ running-left ・ running の違いです。
-
running-right・running-left：ペットを 左右に動かすとき の見た目 -
running：Codexが 作業しているとき の進行中ループ
そのため、running を単なる走り姿にしない方が、状態の意味が伝わりやすくなります。
左右移動のアニメーションについては、下記のX投稿でも触れています。
マウスで左右に動かすときのアニメーションも指定できると気づいたのが、今回の小さな発見でした。
③ hatch-pet で作る6ステップ
仕様が分かったので、ここからはいよいよ作る工程に入ります。
今回は、Codexの hatch-pet スキルを使いました。
手作業で1枚ずつ画像を並べるのではなく、 ペット用の実行フォルダ・行ごとのプロンプト・検証・パッケージ化までをまとめて進められるため です。
全体は次の6ステップに分かれます。
Step 1〜2が準備、Step 3〜5が生成、Step 6が最終化 という流れです。
Step 1：hatch-pet スキルを導入する
まず、Codexのスキル管理で hatch-pet を入れます。
$skill-installer hatch-pet
その後、Codexに作りたいペットを伝えます。
画像がある場合は参照画像を渡してもよいですし、テキストだけでも始められます。
$hatch-pet
小さな狼のCodexペットを作ってください。
落ち着いていて、賢く、好奇心がある雰囲気にしてください。
白いパーカー、青いショーツ、小さな仕事道具を持たせたいです。
ここで重要なのは、最初から全状態を一気に作ろうとしないことです。
まず 「正準の個体」 （Canonical：基準となる1体）を作り、その見た目を基準にして各アニメーション行を作る方が安定します。
生成AIで複数状態のキャラクターを作ると、行ごとに別のキャラクターへ寄ってしまうことがあります。
基準画像を1つ決めてから進めると、顔・配色・体型・小物の一貫性を保ちやすくなります。
なお、実際に試したときは、全体で数十分かかりました。
画像生成・目視確認・やり直し・最終化まで含めると、それなりに時間がかかります。
作業時間には少し余裕を見ておくのがおすすめです。
Step 2：実行フォルダを準備する
少し細かく制御したい場合は、hatch-pet のスクリプトを使って実行フォルダを作れます。
スキルの配置先は環境で異なるため、SKILL_DIR は手元に合わせて調整してください。
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
SKILL_DIR="$CODEX_HOME/skills/hatch-pet"
if [ ! -d "$SKILL_DIR" ]; then
SKILL_DIR="$CODEX_HOME/vendor_imports/skills/skills/.curated/hatch-pet"
fi
python3 "$SKILL_DIR/scripts/prepare_pet_run.py" \
--output-dir /path/to/hatch-runs/galirage-wolf-v3 \
--pet-id galirage-wolf \
--display-name "Galirage Wolf" \
--description "A calm, intelligent pixel wolf companion for AI-native work." \
--pet-notes "A small lavender-gray wolf with teal accents, white hoodie, blue shorts, sneakers, and a tiny work tablet." \
--force
このコマンドを実行すると、次のようなファイルが作られます。
hatch-runs/galirage-wolf-v3/
├── imagegen-jobs.json
├── pet_request.json
├── prompts/
├── references/
└── decoded/
prompts/ には、ベース個体と各アニメーション行のプロンプトが入ります。
imagegen-jobs.json は、どの画像生成ジョブが完了したかを管理するファイルです。
Step 3：ベース個体（正準）を決める
次に、ベース個体を生成します。
この画像が、以後のアニメーション生成の基準になります。
生成した画像を採用する場合は、次のように記録します。
python3 "$SKILL_DIR/scripts/record_imagegen_result.py" \
--run-dir /path/to/hatch-runs/galirage-wolf-v3 \
--job-id base \
--source /path/to/generated/base.png
この記録によって、decoded/base.png と references/canonical-base.png が作られます。
以後の各行では、この canonical-base.png を参照しながら、 同じ個体に見えるように 生成を進めます。
Step 4：9つのアニメーション行を生成する
ベース個体が決まったら、9つの状態を作っていきます。
ここで効くのが、 責務の分け方 です。
サブエージェントには画像生成と目視QAだけを任せ、親エージェントがマニフェスト・記録・最終化を担当する形にしました。
こう分けると、並列に作業しても成果物の整合性を保ちやすくなります。
行ごとの生成が終わったら、採用する画像を記録します。
python3 "$SKILL_DIR/scripts/record_imagegen_result.py" \
--run-dir /path/to/hatch-runs/galirage-wolf-v3 \
--job-id review \
--source /path/to/generated/review.png
今回の review 行は、一度作り直しました。
最初の試作では、虫眼鏡や書類の山を持たせたのですが、 192 × 208 ピクセルでは記号が潰れて、ただの黒い塊 に見えてしまったためです。
装飾を削って表情だけで「集中」を表現したら、ようやくレビュー中らしく見えました。
ここで分かったのが、Codexペットは小さなUI（User Interface：画面上の操作部品）だ、ということです。
画像単体では楽しい装飾でも、アプリ上ではノイズになりやすいので、影・スピード線・浮いた記号・文字・背景は基本的に避けた方が扱いやすいです（具体的な理由は ④の「コツ②」 で後述します）。
Step 5：左右移動はミラー化を検討する
左右移動の体験を良くしたい場合は、running-right と running-left を特に丁寧に確認します。
今回の Galirage Wolf では、running-right を作った後に、running-left はミラー（左右反転）で作りました。
ただし、これは常に正解ではありません。
ミラーで問題ないのは、次の条件をすべて満たす場合に限ります。
- 読める文字やロゴがない
- 左右非対称の意味を持つ装飾がない
- 持っている小物の向きが反転しても不自然ではない
- 光や影の向きに強い意味がない
今回のペットは、文字やロゴを入れていません。
小物も左右反転で意味が壊れない見た目にしたため、ミラーで問題ないと判断しました。
python3 "$SKILL_DIR/scripts/derive_running_left_from_running_right.py" \
--run-dir /path/to/hatch-runs/galirage-wolf-v3 \
--confirm-appropriate-mirror \
--decision-note "No readable text, no side-specific logo, and no asymmetric marking that breaks when flipped."
ここは、見た目の自然さにかなり効きます。
左右に動かしたときだけ違和感が出るペットは、普段使いでじわじわ気になるためです。
Step 6：最終化して Codex に配置する
すべての行が揃ったら、最終化します。
python3 "$SKILL_DIR/scripts/finalize_pet_run.py" \
--run-dir /path/to/hatch-runs/galirage-wolf-v3 \
--package-dir ~/.codex/pets/galirage-wolf
この処理で、フレーム抽出・アトラス合成・WebP化・検証・QA用コンタクトシート作成・プレビュー動画作成・Codex用フォルダへの配置までがまとめて進みます。
最終的には、次のような成果物ができあがります。
hatch-runs/galirage-wolf-v3/
├── final/
│ ├── spritesheet.webp
│ └── validation.json
├── qa/
│ ├── contact-sheet.png
│ ├── review.json
│ └── videos/
└── ...
~/.codex/pets/galirage-wolf/
├── pet.json
└── spritesheet.webp
今回の検証結果では、ok が true、errors が空、warnings も空でした。
画像サイズは 1536 × 1872、セルサイズは 192 × 208、未使用セルは透明化できています。
④ QAと、作って分かった3つのコツ
ここまでで、ペットの実装が終わりました。
最後に、最終化のあとで目視確認するチェック観点と、作ってみて分かったコツを整理します。
QAで見る7つのチェック観点
コンタクトシートと動画で、次の7観点を目視確認します。
自動検証が通っていても、見た目が別キャラクターになっていたら失敗です。
- 全ステートのフレーム数が仕様どおりである
- 顔・体型・配色・小物が同じ個体に見える
- 各フレームがセルからはみ出していない
- 未使用セルに不要なピクセルが残っていない
-
running-rightとrunning-leftが自然に左右移動して見える -
runningが単なる走りではなく、作業中のループに見える -
failed・waiting・reviewがidleと区別できる
特に、idle は控えめにするのがおすすめです。
常に画面にいるペットなので、動きが大きすぎると作業中に気になってしまうためです。
コツ① 最初に正準の個体を固定する
一番効いたのは、 最初に正準の個体を決めること でした。
生成AIで複数の行を作ると、少しずつ顔や服装が変わりがちです。
基準画像を固定すると、状態ごとの表情や動きを変えながら、同じペットとして見せやすくなります。
コツ② 装飾を足しすぎない
もうひとつ大事なのは、 装飾を足しすぎないこと でした。
スピード線・影・背景があると、画像単体ではそれっぽく見えます。
ですが、 小さく・透明背景で・常時表示 という3条件下では、次のような形でノイズになります。
- 影：背景色が変わるアプリ上では浮いて見える
- スピード線：静止状態（
idle・waiting）と動いている状態の対比が崩れる - 文字や記号：
192 × 208ピクセルでは判読不能なドット模様になり、輪郭がぼやける
review 行を作り直したときに、まさにこの3つ目が起きました。
装飾は単独画像で映えても、UIの一部として常に画面に居続ける条件下では、引き算の方が効きます。
コツ③ 実際に動かして、フレームのズレを目視確認する
左右移動は、必ず実際にペットを動かして目視確認してください。
画像単体では綺麗に見えても、アプリ上で動かすとフレームがズレて見えることがあります。
running-right と running-left はコンタクトシートだけでは判断しにくく、実際に左右に動かして初めて気づく不自然さが出やすいためです。
まとめ
Codexのペット作りは、単なる画像生成ではありません。
小さなUIとして、 状態・サイズ・透明背景・ループの自然さ まで含めて設計する作業です。
今回のポイントを、もう一度3つにまとめます。
- まず正準の個体を決める（一貫性の起点）
- 9つの状態を、
8列 × 9行 / 1536 × 1872の仕様に合わせて作る -
running-right・running-leftは実際に動かしてフレームのズレを目視確認する
Codexに自分だけの相棒がいると、開発環境が少しだけ自分の場所になります。
こういう小さな遊び心も、AIネイティブな働き方を楽しく続けるための大事な要素なのかもしれません。
最後に
最後まで読んでくださり、ありがとうございました！
この記事を通して、少しでもあなたの学びに役立てば幸いです✨
参考文献
Discussion