Troubleshooting
Fix Codex Pet issues
Most install problems come from folder placement, missing files, or a spritesheet that does not match the expected atlas.
Why is my custom pet not showing in Codex?
Check that the folder lives under ~/.codex/pets/<pet-name>/ and contains pet.json plus spritesheet.webp.
Why does the animation look wrong?
The spritesheet may be unreadable, not transparent, or arranged in a way the current Codex runtime cannot animate cleanly.
Should I restart Codex after installing a pet?
Yes. Restart Codex after placing a new pet folder or installing new skills.
Why are Codex Pet animations frozen on macOS?
macOS Reduce Motion settings can stop or reduce desktop animations. Check the reduce motion guide if the pet appears but does not animate.
How do I verify the install path?
Open your home folder and confirm the pet package is inside ~/.codex/pets/<pet-name>/ with pet.json and spritesheet.webp at the top level.
Compare your package with the format spec. Read the reduce motion guide