Download and install Codex pets
A Codex pet download is a package with a manifest and a spritesheet. Once the folder is installed, use /pet inside Codex, or open Settings, choose Appearance, then Pet to change the active companion. If you are still choosing a package, start in the Codex pet gallery. If you need the concept first, read what Codex pets are.
Pick the right path
Start here when you want an existing package with pet.json and a spritesheet already prepared.
New petGenerate with hatch-petUse the builder only when you need a new package generated from a prompt instead of installing a finished gallery pet.
Check firstPreview before enablingValidate the spritesheet visually before switching the active pet in Codex.
Generator skill
~/.codex/skills/hatch-pet/ SKILL.md scripts/ references/
hatch-pet is the generation workflow skill. It is separate from the finished pet package. If Codex cannot discover this skill, a copied prompt should stop at the install step instead of claiming a pet was generated.
Folder contract
~/.codex/pets/my-pet/ pet.json spritesheet.webp
The manifest identifies the pet and points Codex to the spritesheet file inside the same package folder.
pet.json
{
"id": "my-pet",
"displayName": "My Pet",
"description": "A concise pet description.",
"spritesheetPath": "spritesheet.webp"
}Atlas
The animation rows are idle, running right, running left, waving, jumping, failed, waiting, running, and review.
# After downloading tater-codex-pet.zip mkdir -p "$HOME/.codex/pets/tater" unzip -o "./tater-codex-pet.zip" -d "$HOME/.codex/pets/tater" # In Codex /pet # Or manually Settings -> Appearance -> Pet -> choose tater
Download the package zip first, then run this command from the folder that contains the zip file. After installation, use /pet or open Settings, choose Appearance, then Pet.
How to use
Choose a finished Codex pet in the gallery and download its package zip before creating the local pet folder.
Make a dedicated ~/.codex/pets/<pet-id>/ directory so Codex can discover the package by id.
Place pet.json and spritesheet.webp in that folder, keeping the manifest id aligned with the folder name.
Use a 1536 by 1872 spritesheet with 8 columns, 9 rows, 72 frames, and 192 by 208 frame cells unless your renderer contract changes.
Restart or refresh Codex if needed, then use /pet or open Settings -> Appearance -> Pet and choose the installed Codex pet.
Install FAQ
Open the Codex pet gallery, choose a pet, and download its package zip from the pet detail page. The package should contain pet.json and spritesheet.webp so you can place both files under ~/.codex/pets/<pet-id>/.
No. hatch-pet is for generating a new pet, not for using an existing package. To use an existing Codex pet, add its pet.json and spritesheet.webp under ~/.codex/pets/<pet-id>/ or use the pet detail page's AI setup prompt.
Custom Codex pets go under ~/.codex/pets/<pet-id>/. The folder should contain pet.json and spritesheet.webp, with the manifest spritesheetPath pointing to the image file.
Use /pet inside Codex after the package is in the local pets folder, or open Settings -> Appearance -> Pet and choose the installed pet. If the custom pet does not appear, confirm the folder name, pet.json id, and spritesheetPath all match the installed files.
The example Codex pets on this site use a 1536 x 1872 spritesheet with 8 columns, 9 rows, and 192 x 208 frame cells. Keep that size unless your Codex pet renderer contract changes.
For local Codex installation, spritesheetPath should point to the image file inside the pet folder. For web preview, this tool can load a browser-accessible URL because the React renderer only needs an image src.
The most common cause is an image that does not follow the shared atlas dimensions. Check that the spritesheet is 1536 x 1872, uses 8 columns and 9 rows, and keeps each frame aligned to 192 x 208 cells.