HELP / ONE-MINUTE CHECKLIST
DON'T REINSTALL YET. IT'S USUALLY ONE FOLDER DEEP.
File location, restart steps, and format details live here. Run the shortest checks first, then decide what to do next.
CHECK THESE FIRST
THE ONE-MINUTE CHECK
- 1The ZIP is extracted, not placed unopened in pets.
- 2pet.json sits beside spritesheet.webp.
- 3Codex was fully quit before reopening.
FAQ
QUESTIONS, OUT IN THE OPEN
Open any question for a direct answer. No login required.
Why does my pet not appear after installation?＋
Confirm the final path is .codex/pets/<pet-id>/pet.json and keep pet.json beside spritesheet.webp. Then fully quit Codex Desktop—not just its window—and reopen it.
Can I reinstall the same pet?＋
Yes. Rename or back up the existing folder first. The install request provided here stops at a name conflict and never overwrites silently.
Where is the path on macOS and Linux?＋
The default path is ~/.codex/pets. If CODEX_HOME is set, use CODEX_HOME/pets instead.
Why do I have two folders with the same name?＋
The ZIP already contains the complete pet folder. Move that whole folder into pets instead of extracting it into another folder with the same name. The final path should be pets/<pet-id>/pet.json.
Is this an official OpenAI pet library?＋
No. This is an independent project built around the Codex Desktop custom-pet format and is not an official endorsement.
Can I redistribute or commercialize the artwork?＋
The site code and pet artwork use different terms. Review LICENSE and ASSET-LICENSE.md in the GitHub repository before reuse.
Pet file details (advanced)
ADVANCED / PET FILES
TWO FILES. ONE PRECISE STRUCTURE.
Every pet consists of a manifest and the real atlas. Site previews read the same spritesheet—not a separate concept animation.
<pet-id>/
├─ pet.json
└─ spritesheet.webp- Atlas
- 1536 × 2288
- Grid
- 8 × 11
- Cell
- 192 × 208
- Version
- v2