Create a custom Codex pet with hatch-pet
A custom Codex pet is a small package with metadata and animation frames. The clean workflow is to generate with hatch-pet, verify the package files, preview the animation, then decide whether to keep it local or publish it to a community directory.
Use $skill-installer hatch-pet, then reload skills from the Codex command menu so the new skill is available.
Ask hatch-pet to create a pet from a description, project theme, or visual idea. Keep the prompt specific enough to produce a compact readable companion.
Confirm the package includes pet.json and spritesheet.webp. These files describe the pet and provide the animation frames.
Preview the package in Codex or a community validation tool before publishing. Watch for broken frames, wrong atlas alignment, or missing metadata.
Share only packages you have rights to publish. If the pet is personal, keep it local and refresh custom pets from the Codex Appearance settings.
~/.codex/pets/<pet-id>/ ├── pet.json └── spritesheet.webp
Codex reads custom pets from this folder when you refresh pets in Settings > Appearance > Pets.
- Package includes both metadata and spritesheet files.
- Animations preview correctly across idle, running, waiting, and review states.
- Description and tags match the visible pet.
- Assets do not rely on private images or rights you cannot share.
- Community page includes a clear download or share URL.
Custom Codex Pet FAQ
Answers about hatch-pet, package files, validation, and sharing custom pets.
What files does a custom Codex pet need?+
A custom Codex pet package needs pet.json and spritesheet.webp. The JSON file describes the pet and animation metadata, while the spritesheet contains the visual frames. Some sharing workflows also package both files into a .codex-pet.zip archive.
Should I use hatch-pet or the codexpets.org builder?+
Use hatch-pet when you want to generate a new custom pet from inside the Codex workflow. Use the codexpets.org builder when you want to draft a structured hatch-pet brief before running it, or use the preview tool to validate an existing spritesheet. The two workflows complement each other: the builder helps plan, hatch-pet executes.
Can I share a Codex pet after creating it?+
Yes, if you have a complete package and the rights to share the visual concept. Community directories like codexpets.org provide gallery pages, AI setup prompts, and download paths. Before publishing, avoid assets that misuse brands, copyrighted characters, or private images without permission.
How should I test a custom Codex pet package?+
Test the package by confirming that pet.json loads, spritesheet.webp displays, and the expected animations play without frame alignment issues. Use the codexpets.org preview tool to check the spritesheet against the standard Codex atlas layout (8 x 9 grid, 192 x 208 cells) before sharing.