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.
Compare your package with the format spec.