Download and install Codex pet packages
A Codex pet download is a package zip with a manifest and a spritesheet. Once the folder is installed, use /pet inside Codex, or open Settings, choose Appearance, then Pets 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.
Package download contents
A downloadable package from this site is intentionally small: it should unzip into one pet folder with pet.json and spritesheet.webp. The manifest names the pet, and its spritesheetPath should point at the spritesheet file in the same folder. If those files are missing or renamed, preview the package before installing it.
When you are checking a Codex pet.json file, treat spritesheetPath as the pointer from the manifest to the actual image file. Keep it relative for a local package, then use the preview tool if the path or atlas dimensions are uncertain.
Start from a specific pet detail page so the package id, manifest, spritesheet, and install command all describe the same companion.
2Preview the spritesheetCheck the 9-state atlas and manifest before you move the files into the local Codex pets folder.
Community ecosystemBrowse Petdex packagesPetdex offers a broader community directory and CLI. Check its current platform support before choosing that installation path.
3Confirm the package conceptRead the explainer if you need the difference between official Codex context and this community package workflow.
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. Because the installed skill can evolve, use its reported atlas and manifest contract for newly generated pets rather than assuming the catalog package dimensions.
Folder contract
~/.codex/pets/my-pet/ pet.json spritesheet.webp
The manifest identifies the pet, and spritesheetPath 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 -> Pets -> 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 Pets. Use Refresh custom pets if the package does not appear immediately.
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.
Use /pet or open Settings -> Appearance -> Pets and choose the installed Codex pet. If it is missing, use Open folder to confirm the active directory, then Refresh custom pets.
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 -> Pets and choose the installed pet. Use Open folder or Refresh custom pets when those controls are available. If the pet still does not appear, confirm the folder name, pet.json id, and spritesheetPath all match.
The downloadable Codex pets on this site use a 1536 x 1872 spritesheet with 8 columns, 9 rows, and 192 x 208 frame cells. For a newly generated pet, follow the current installed hatch-pet and renderer contract and verify the reported dimensions before installation.
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.
Codex and WSL can disagree about Windows and Linux path forms. Keep the package under the Codex home used by the running app, use the Pets settings Open folder action when available, and refresh custom pets after copying the files.
Do not rely on that today. Custom packages provide the manifest and spritesheet, while the Codex app still owns animation timing, frame sequences, state chaining, and activity-event mapping.