Your Pets Folder, Dissected: The ~/.codex/pets Structure

Where the .codex pets folder sits

Every pet you install ends up in one place. On macOS and Linux that is ~/.codex/pets; on Windows it is %USERPROFILE%\.codex\pets. Codex reads the .codex pets folder once at startup and treats each subdirectory directly inside it as one pet. Files anywhere else on the disk might as well not exist.

That single rule explains most reports of a pet that installed and then never showed up. Codex does not scan recursively, so a pet sitting at ~/.codex/pets/cats/mochi never loads, while the same folder at ~/.codex/pets/mochi loads fine.

Pets directory layout at a glance

The pets directory layout is flat on purpose. One level of subfolders, two or three files in each, and nothing else in the parent.

• ~/.codex/pets/ — the parent. Only pet subdirectories belong here
• <pet-id>/ — one pet. The folder name is the id Codex uses internally
• spritesheet.webp — 1536x1872, nine animation states at eight frames each
• pet.json — display name, frame counts, timing. No image data and no colors
• Anything extra, such as the photo you uploaded, is skipped by Codex and harmless to leave

What sits inside a codex pets subfolder

Open any one of them and you get the same small set of files every time. The generator writes them as a package, which is why you can download a pet, move the folder somewhere else, and have it still work.

• spritesheet.webp: the pixels. Nine rows, one per animation state, eight frames per row
• pet.json: roughly forty lines of metadata. Id, display name, and per-state timing
• Preview or readme files: some generators include them, Codex ignores them
• Keep the pair together. A sprite sheet without its pet.json renders nothing at all

pet.json is the only file worth opening

It is short enough to read in one sitting, and only two of its fields matter in practice.

The id has to match the folder name. When they disagree, Codex keys the pet under the folder and the picker shows a name you did not set. The displayName is the label in the picker and the one field you can edit by hand with no consequences.

• id — must equal the folder name, used for lookups
• displayName — the label in the pet picker, safe to edit
• states — nine entries, each with a frame count and a duration in milliseconds
• No color data whatsoever. Editing pet.json will never change how a pet looks

Edits you can make by hand, and edits you cannot

Hand editing is fine for a short list of things and a bad idea for everything past it.

• Fine: edit displayName, delete a subfolder to uninstall, copy a subfolder to another machine
• Fine: keep a backup zip in the parent folder, but never inside a pet subfolder
• Not fine: resizing spritesheet.webp. The dimensions are part of the contract, covered in /blog/spritesheet-dimensions
• Not fine: changing frame counts unless you redrew the frames too
• Not fine: changing colors here. Colors live in the pixels, so a new palette means regenerating at codexpetgenerator.com

Keep the folder boring

The plainer the folder, the fewer surprises. One subdirectory per pet, no nesting, no duplicate ids, and a backup zip kept somewhere outside it.

Generate the next one at codexpetgenerator.com, drop the folder into ~/.codex/pets, and you are done. The terminal install walkthrough is at /blog/install-codex-pet-terminal, the backup routine is at /blog/backup-codex-pets-guide, and the plan limits sit on /pricing.