Sync Your Codex Pet Across Work and Home Machines

What you are actually moving when you copy a pet to another computer

A Codex pet is two files: spritesheet.webp and pet.json. That is the entire package. When you copy pet files to another computer you are moving those two items inside one folder, and the folder name has to match the name field inside pet.json. Nothing else on the machine matters. There is no registry entry, no installer step, and no license check tied to the hardware.

That is why codex pet sync is less work than people expect. There is no account to sign into and no cloud profile to restore from. The pet lives in a directory Codex reads when it launches, so if the same directory exists on a second machine with the same contents, the same pet shows up there.

• spritesheet.webp: the frames, 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

Where the pets folder lives on each machine

On macOS and Linux the path is ~/.codex/pets. On Windows it is %USERPROFILE%\.codex\pets. If the folder does not exist yet, create it. Codex reads the directory at launch, so a pet dropped in before you open the app appears on the very first run.

Write the path down for both machines before you start moving anything. Most failed syncs are not sync problems: the pet landed inside a second .codex folder created by a different installer, or one level too deep inside a subfolder Codex never scans.

• macOS and Linux: ~/.codex/pets/
• Windows: C:\Users\<you>\.codex\pets\
• Confirm with ls ~/.codex/pets, or dir %USERPROFILE%\.codex\pets on Windows

Three ways to sync your pets folder between machines

Pick one method and stay with it. Mixing them is how you end up with two slightly different pets that both look correct until you screenshot them side by side.

• Zip and copy: zip the pet folder, move it by USB stick, AirDrop or email, unzip it into the pets folder on the second machine. Right choice for a one-off move.
• Synced drive: place ~/.codex/pets inside a folder managed by Dropbox, iCloud Drive, OneDrive or Syncthing and let it replicate. Right choice when you edit pets on both machines.
• Private git repo: commit the folder and pull on the other machine. Right choice if you already version your dotfiles and want a history of changes.

Multi-machine setup: what breaks

Codex pet multiple machines setups fail in a short list of repeatable ways. Path drift is the most common: a WSL home directory and a Windows home directory are not the same place, and a pet copied into one stays invisible to Codex running from the other.

The second is a name mismatch after a rename. If you rename the folder on one machine and the sync only carries file contents, the other machine keeps the old folder name while pet.json declares a new one. Codex skips it without an error message, which makes it look like a bug in the pet rather than a mismatch.

The third is a read that happened too early. Codex reads the folder at launch, so a pet that arrives while Codex is open will not show up until you quit and reopen it.

• Pet missing on one machine only: check which .codex directory Codex actually reads
• Pet appears then disappears: a sync client is mid-write, wait for it to finish
• Pet renders as a blank square: spritesheet.webp did not finish transferring

Keeping pet.json in step across machines

Treat pet.json as the source of truth. When you adjust animation timing or state names on one machine, export the folder again and let the sync carry the whole thing across. Editing pet.json in two places produces two pets that drift apart quietly, and quiet drift is worse than a pet that fails to load, because a failure is at least visible.

If you regenerate a pet from a photo, download the fresh ZIP and overwrite the folder rather than merging files. A generator emits the spritesheet and pet.json as a matched pair, and pairing a new image with an old JSON is the usual reason frames play at the wrong speed.

One pet, two machines

Generate once, then point both machines at the same folder. That is the whole habit, and it takes about two minutes to set up.

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 which format to carry between machines.