INSTALL
Install a pet in a minute.
Every Hatchery pack is a zip holding one folder: pet.json plus the sprite sheet. Put that folder in the right place and the app finds it. There is nothing else to configure.
What is inside the zip
lil-mayo/ pet.json the name, the description, the sheet filename spritesheet.webp 1536 x 1872, 8 columns by 9 rows, 192 x 208 per cell INSTALL.txt the same two commands you see below
Some packs ship spritesheet.png instead of WebP. That is fine. pet.json always names the file it actually contains.
01 The Codex desktop app
- Unzip the pack into your pets folder. macOS and Linux use
~/.codex/pets/. - Open Settings, then Appearance, then Pets. Hit refresh so the app re-reads the folder.
- Pick your pet from the list. It shows up under the name in
pet.json.
unzip -o lil-mayo.zip -d ~/.codex/pets/
02 The Codex CLI
Same folder, same files. Once the pack is unzipped, run /pets inside a Codex session and select the pet from the list. If you install a pet while a session is already open, run /pets again to pick up the new folder.
/pets
03 Windows
The pets folder lives under your user profile. PowerShell expands $env:USERPROFILE for you, so the command below works from any directory as long as the zip is in the one you are standing in.
Expand-Archive lil-mayo.zip -DestinationPath "$env:USERPROFILE\.codex\pets\" -Force
The result should read C:\Users\you\.codex\pets\lil-mayo\pet.json. If you end up with ...\pets\lil-mayo\lil-mayo\pet.json you have one folder too many, so move the inner one up.
04 OpenPets: Claude Code, Cursor, OpenCode, Gemini CLI, Pi CLI
Those harnesses do not read Codex pets directly. OpenPets is the community bridge that does, and it uses the same 8 by 9 atlas, so a Hatchery pack works unchanged. Install OpenPets for your harness, then put the pet folder where OpenPets keeps its pets, which on most setups is the same .codex/pets directory it already reads from.
OpenPets moves faster than this page does. If the folder it watches has changed, its own readme is the source of truth, and the pack itself never needs to change.
TROUBLESHOOTING
When it does not work.
The pet does not show up in the list
Nine times out of ten it is folder depth. The app expects pets/<id>/pet.json, exactly one folder deep. Unzipping into a subfolder, or unzipping twice, buries it a level too far.
The other cause is a filename mismatch: spritesheetPath inside pet.json has to match the image file sitting next to it, extension included. After fixing either one, refresh the pets list, or run /pets again in the CLI.
The edges look jagged or fuzzy
Sprites are drawn at a fixed 192 by 208 per cell. If the surface renders them at a fractional zoom, straight edges pick up stair steps and soft halos. Integer zoom levels, 100 or 200 percent, look clean. On a HiDPI screen the app usually handles this for you.
If it is not zoom, it is the source art. A busy or gradient heavy pet leaves a soft fringe the chroma key cannot cut cleanly. Re-hatch that row from the builder, or build again with a simpler description and the pixel or sticker style, which both hold a hard outline.
The pet is invisible, or it is a solid block
The sheet lost its transparency somewhere. Re-saving a sprite sheet in an editor that flattens alpha does this, and so does converting it to JPEG. Download the pack again and do not re-encode it. Hatchery checks the sheet before it lets you download, so a fresh pack is always clean.
The folder ended up one level too deep
Some unzip tools wrap the archive in a folder of their own, which gives you pets/lil-mayo/lil-mayo/pet.json. Move the inner folder up one level and delete the empty wrapper. The -o and -Force flags in the commands above prevent this on a re-run.
Nothing renders inside tmux
Pets are not supported under tmux. Run the CLI in a plain terminal window to see them. The same goes for most multiplexers and for terminals without image support. That is a limit of the host, not of the pack.
I want to edit the sprite sheet myself
Go ahead. Keep it at 1536 by 1872, keep the row order, and make sure every unused cell is fully transparent with zero RGB. That last one catches people out: some editors leave colour data behind alpha and the validator rejects it. Row order is idle, run right, run left, waving, jumping, failed, waiting, working, review.
No pet yet?
Choose a look, shape the details, and the builder draws the whole pack.