Codex Desktop Updates: What's New for Pets

What a codex pet update actually touches

A codex pet update arrives inside the Codex desktop app. There is no pet updater to run and nothing to reinstall. When you install a new desktop build, the code that draws your sprite comes along with it, and whatever that build changed in the drawing path shows up the next time you launch.

That is the part people get wrong. They go looking for a pet release note. The pet is two files you own, a spritesheet.webp and a pet.json, plus the app code that reads them, and only the second half gets replaced.

• Your pets folder: untouched by the installer
• The spritesheet and pet.json you generated: untouched
• Your custom palette and animation states: untouched
• The renderer, the animation timer and the default pet set: replaced with the new build

Where the pet files sit during an upgrade

Everything you own lives under the pets directory in your home folder: ~/.codex/pets/ on macOS, %USERPROFILE%/.codex/pets/ on Windows. Installers write to the application directory, which is a different place, so an upgrade has no reason to walk into your pets folder.

One exception is worth knowing. Some builds change the default pet that ships with the app. If you never generated your own, the pet you see can be swapped for whatever the new build picked. Generate a pet once and you stop being affected, because yours lives in your home folder rather than inside the app.

• macOS: ~/.codex/pets/<pet-name>/
• Windows: %USERPROFILE%/.codex/pets/<pet-name>/
• Each folder holds one spritesheet.webp and one pet.json
• Layout, backups and sync are covered at /blog/codex-pets-folder-structure, /blog/backup-codex-pets-guide and /blog/sync-codex-pet-across-machines

Reading a codex pet changelog without the noise

Changelogs are written for the whole app, and the pet-related lines hide somewhere in the middle. The words worth scanning for are renderer, window, assets and sprite. A line about model routing or API keys will not change anything you can see in the corner of your screen.

When a release note does mention pets, it tends to be about the animation frame budget, the default pet set, or how a malformed pet.json gets handled. Anything else you notice is usually a side effect of a larger interface change rather than a pet change.

• Animation or frame budget changes: your spritesheet keeps working, the timing can feel different
• Default pet set changes: only affects people who never generated one
• pet.json validation changes: a pet that loaded before may now be rejected, usually over a missing field
• Window or tray changes: the corner the pet occupies can move, which reads as a missing pet

What to check before you report a broken pet

Most reports of an update breaking a pet turn out to be one of four things, and all four take under a minute to rule out. Run them in this order before you write anything up.

• Quit Codex completely and relaunch. A hot reload does not always restart the animation timer.
• Confirm the folder name in your pets directory matches the name field in pet.json exactly, including capital letters.
• Open the spritesheet in an image viewer. If it will not open, the file was damaged before the update.
• Check that the Codex window is on the monitor you are looking at. Pets do not follow your eyes.

Where to go from here

Generate a pet at codexpetgenerator.com, keep the folder in your home directory, and updates stop being an event. The generator writes the same two files no matter which desktop build you are on, so a pet made today keeps drawing after the next release.

The wider picture is at /blog/codex-pet-ecosystem, /blog/pets-library-explained covers keeping several pets straight in one folder, and /blog/backup-codex-pets-guide is a ten minute insurance policy against a bad afternoon. Start at /blog for the rest.