How to Create a Codex Pet: Step-by-Step Guide

What you need before you start

The whole process is shorter than the setup list suggests, but having these four things ready means you will not stop halfway.

• The OpenAI Codex desktop app, installed and launched at least once so its config directory exists.
• One photo of your pet — a cat, dog, hamster, tortoise, or anything else you want on your desktop.
• A Codex-aware generator. This walkthrough uses codexpetgenerator.com, which outputs the spritesheet and pet.json Codex expects.
• A terminal or file manager, for copying the finished folder into the pets directory.

Step 1: Choose and prepare your photo

Photo choice drives output quality more than any setting in the generator. A single subject, centered in frame, lit evenly, and shot against a plain background gives the model the least to guess about.

Facing the camera helps a lot. Profile shots work, but three-quarter views tend to read better once reduced to a pixel grid, because more of the face survives the simplification. Avoid heavy filters and busy backgrounds — both get interpreted as part of the animal.

Step 2: Generate the pixel-art base

Upload the photo. The generator removes the background, detects the pose, and renders a pixel-art base character — typically within about 90 seconds. Nothing is installed yet at this stage; you are looking at a preview you can still change.

This is the moment to regenerate rather than push ahead. If the silhouette is wrong or the colours are off, a different crop or a slightly higher-contrast version of the same photo will usually beat any amount of post-processing.

Step 3: Approve the base

Once the base looks right, approve it. Approval is what triggers the expensive part: the generator renders all nine animation states, composes them into a single 1536x1872 spritesheet, writes the matching pet.json, and packs both into a ZIP.

Nine states means 72 individual frames. Doing that by hand is what makes manual spritesheets so time-consuming, and it is the main reason to use a generator at all.

Step 4: Download the package

Download the ZIP and extract it. Inside you should see exactly two files sitting side by side: spritesheet.webp and pet.json. If they are nested one level deeper inside a folder from the extraction, note the folder name — that inner folder is what Codex will read.

The folder name matters. Whatever you end up calling it must match the name field inside pet.json, character for character.

Step 5: Install into the pets directory

Copy the folder into ~/.codex/pets on macOS, or %USERPROFILE%\.codex\pets on Windows. If the pets directory does not exist yet, create it — Codex will not build it for you on first run.

Open pet.json and read the name field, then rename the folder you just copied so it matches that value exactly. A folder called my-cat-v2 whose JSON declares name "my-cat" is enough to make the loader skip the pet without any error message.

Step 6: Restart and confirm

Fully quit Codex — Cmd+Q on macOS, or exit from the tray icon on Windows — then relaunch and wait a few seconds. Closing the window is not sufficient on either platform, because the process keeps running in the background and never re-reads the pets directory.

Your pet should now be on your desktop. If it is not, resist the urge to start over: the failure is almost always one of four things, and all four are quick to check.

What to do when nothing appears

Work through these in order. Each one takes under a minute, and together they account for the overwhelming majority of "I installed it but it is not there" reports.

• Confirm the restart was a real restart — process fully exited, not just the window closed.
• Check that the folder name and the name field in pet.json are byte-identical, including hyphens and capitalisation.
• Verify spritesheet.webp is named exactly that and sits directly beside pet.json, not in a nested subfolder.
• Validate the JSON with node -e "JSON.parse(require('fs').readFileSync('pet.json','utf8'))" — a trailing comma is enough to break it.

Making changes later

To swap your pet, generate a new one and give it a distinct name, or replace the files in the existing folder — keeping the name consistent means you do not have to redo the install steps.

If you want several pets, give each one a unique name field. Two folders declaring the same name is a known failure mode: the loader picks one and silently ignores the other, which looks exactly like an install that did not work.