How to Install a Custom Codex Pet from the Terminal

What you need before you start

A pet package with two files: spritesheet.webp (the animation frames) and pet.json (the config). If you generated it on PetGen, it downloads as a ZIP you can extract anywhere.

You do not need the Codex UI open for the install itself. Terminal or PowerShell is enough.

Where pets actually live: ~/.codex/pets

Codex scans a single directory for pets: ~/.codex/pets. The tilde means your home folder, so on Windows that is C:\Users\<you>\.codex\pets. Each pet is one subfolder inside it, containing spritesheet.webp and pet.json.

The folder name and the name field inside pet.json have to match. I have burned ten minutes on this exact mismatch more than once, so check it before you restart.

macOS: the two-line install

Open Terminal and run:

mkdir -p ~/.codex/pets && cp -r ~/Downloads/my-pixel-pet ~/.codex/pets/

Then quit Codex completely (Cmd+Q) and relaunch. Your pet should appear.

Want a quick sanity check first? Run ls ~/.codex/pets and confirm your folder is there before restarting.

Windows: the PowerShell equivalent

Open PowerShell and run:

Copy-Item -Recurse "$env:USERPROFILE\Downloads\my-pixel-pet" "$env:USERPROFILE\.codex\pets\"

If the .codex folder does not exist yet, create it first with: New-Item -ItemType Directory "$env:USERPROFILE\.codex\pets" -Force

Then fully exit Codex (check the tray) and launch again.

Verifying the install like a nerd

Two commands tell you most of what you need: ls ~/.codex/pets shows the folder, and cat ~/.codex/pets/<name>/pet.json shows the config Codex will read.

Check that the name field in pet.json matches the folder name exactly, and that spritesheet.webp sits next to it. If both are right and the pet still does not show, it is almost always a restart problem, not a file problem.

Common terminal mistakes

• Typing .codex with a capital C — it is lowercase.
• Copying the ZIP instead of the extracted folder — Codex does not unzip for you.
• Missing the trailing backslash on Windows when copying folders.
• Forgetting to fully quit Codex; closing the window is not enough.

Uninstalling is just deleting a folder

rm -rf ~/.codex/pets/<name> on macOS, or Remove-Item -Recurse on Windows, then restart Codex. No leftover registry entries, no config changes — it is gone.

If you want more pets to pick from, generate one at codexpetgenerator.com and drop it into the same folder. That is the whole workflow.