Back Up Your Pets: Do Not Lose Your Pixel Companion

What a pet backup has to contain

The thing you are saving is the pet folder, not the image on its own. spritesheet.webp holds every frame, while pet.json holds the id, the display name and the timing for each state. A backup missing pet.json cannot be restored, because that file is how Codex tells one pet from another.

You can check an archive by opening it. If both files are there and the folder name matches the name inside pet.json, it will restore. If you see one file, or a folder nested inside another folder, it will not.

• spritesheet.webp: every frame, usually eight or nine states stacked in one image
• pet.json: the id, displayName, and the timing for each state
• the folder wrapping both, named to match displayName
• the original photo you generated from, optional but worth keeping if you may regenerate later

Three backup habits that hold up

Pick one method and stay with it. What breaks is rarely the method itself. It is switching between methods halfway through and losing track of which copy is the current one.

• Zip and file away: compress the pet folder into something like pets-backup-2026-10.zip and drop it in cloud storage. The right choice if you set pets up once and leave them alone.
• Synced directory: point Dropbox, iCloud Drive, OneDrive or Syncthing at ~/.codex/pets and let it replicate. The right choice if you edit pets often.
• Private git repo: commit the folder so every change has a history. The right choice if you already version your dotfiles.

Where the backup has to live to count

A second copy on the same machine is not a backup. An external drive carried in the same bag is one layer better, but both still disappear together. The cheapest answer that actually works is a cloud folder you are already paying for.

Decide what you are protecting against. Disk failure needs a copy somewhere else entirely. Accidental deletion needs a copy with version history. Reinstalling the operating system needs a copy you can reach before you sign back into anything.

• A cloud drive already in your routine: lowest effort, survives disk failure
• A second machine you sync with: fine, but not independent if both pull from the same source
• An encrypted archive in cold storage: right for pets made from photos you no longer have

Restoring a pet from a backup

Restoring is the install walkthrough run in reverse. Unzip into ~/.codex/pets on macOS or Linux, or C:/Users/<you>/.codex/pets on Windows, check that the folder name matches the name field inside pet.json, then quit Codex completely and open it again.

Codex reads the pets directory once at launch, so a pet that arrives while the app is running stays invisible until you restart. If it is still missing after a restart, check the folder name first. A mismatch produces no error message, just an empty corner of the screen.

How backups fail

The ways a codex pet backup stops working are a short list, and they repeat.

• Image only: pet.json is missing, so Codex cannot identify the pet
• Renamed after the fact: the pet.json inside the archive still declares the old name
• Nested one level too deep: you archived the parent directory, and Codex does not scan subfolders
• Never tested: the archive looks fine right up to the day you need it
• Backed up once, two years ago: the current pet has different animation timing

A habit that costs ten minutes a year

Back up when you generate a pet, and again whenever you edit one. That is the whole schedule. Two minutes at generation time, thirty seconds after an edit, one archive with the date in its name.

Test the restore once, on a machine that does not have the pet. Unzip, restart Codex, and confirm the pet animates. A backup you have never restored is a guess.

Start at / to turn a photo into a pixel companion, follow the install walkthrough at /blog/how-to-install-codex-pet for the path on each operating system, and read /blog/export-formats-explained before you decide what to put in the archive.