INSTALL
One line, then restart the agent.
Every pack is a zip holding one folder: pet.json plus the sprite sheet. The agent reads that folder from ~/.codex/pets/. The one-liners below put it there. Nothing else to configure.
00 The one-liners
Replace <id> with the last part of a gallery URL, for example byte-toad. The Install button on every gallery card copies the right line with the id filled in.
curl -fsSL https://3ps.online/pets/install.sh | sh -s -- <id>
& ([scriptblock]::Create((irm https://3ps.online/pets/install.ps1))) <id>
Each script downloads the zip, checks for the tools it needs, unzips into ~/.codex/pets/<id>/ (Windows: %USERPROFILE%\.codex\pets\<id>\) and prints what it did. --dir <path> (PowerShell: -Dir) targets another folder, for an OpenPets setup that reads somewhere else. Both scripts are short and readable: install.sh, install.ps1.
What is inside the zip
byte-toad/ pet.json the name, the description, the sheet filename spritesheet.webp 1536 x 1872, 8 columns by 9 rows, 192 x 208 per cell INSTALL.txt the same commands you see on this page
Some packs ship spritesheet.png instead of WebP. That is fine. pet.json always names the file it contains.
01 The Codex desktop app
- Put the folder in your pets folder. The one-liner does it. By hand: unzip into
~/.codex/pets/. - Open Settings, Appearance, Pets. Refresh so the app re-reads the folder.
- Pick it from the list. It shows up under the name in
pet.json.
unzip -o byte-toad.zip -d ~/.codex/pets/
02 The Codex CLI
Same folder, same files. Once the pack is in place, run /pets inside a Codex session and select it from the list. If you install one while a session is already open, run /pets again to pick up the new folder.
/pets byte-toad
03 Windows, by hand
The pets folder lives under your user profile. PowerShell expands $env:USERPROFILE for you, so the command below works from any directory as long as the zip is in the one you are standing in.
Expand-Archive byte-toad.zip -DestinationPath "$env:USERPROFILE\.codex\pets\" -Force
The result should read C:\Users\you\.codex\pets\byte-toad\pet.json. If you end up with ...\pets\byte-toad\byte-toad\pet.json you have one folder too many, so move the inner one up.
04 ChatGPT on the web
ChatGPT takes the sheet directly. Open Personalization, then Pets, and upload spritesheet.webp from the zip. The upload wants a transparent PNG or WebP at exactly 1536 x 1872 pixels, no larger than 20 MiB. Every pack from here meets that.
05 OpenPets: Claude Code, Cursor, OpenCode, Gemini CLI
Those harnesses do not read Codex pets directly. OpenPets is the community bridge that does, and it uses the same 8 by 9 atlas, so a pack from here works unchanged. Install OpenPets for your harness, then put the folder where OpenPets keeps its pets, which on most setups is the same .codex/pets directory. If yours reads elsewhere, pass that folder to the one-liner with --dir.
OpenPets moves faster than this page does. If the folder it watches has changed, its own readme is the source of truth, and the pack itself never needs to change.
TROUBLESHOOTING
When it does not work.
It does not show up in the list
Nine times out of ten it is folder depth. The app expects pets/<id>/pet.json, exactly one folder deep. Unzipping into a subfolder, or unzipping twice, buries it a level too far. The one-liner gets this right.
The other cause is a filename mismatch: spritesheetPath inside pet.json has to match the image file sitting next to it, extension included. After fixing either one, refresh the list, or run /pets again in the CLI.
The edges look jagged or fuzzy
Sprites are drawn at a fixed 192 by 208 per cell. If the surface renders them at a fractional zoom, straight edges pick up stair steps and soft halos. Integer zoom levels, 100 or 200 percent, look clean. On a HiDPI screen the app usually handles this for you.
If it is not zoom, it is the source art. A busy or gradient heavy design leaves a soft fringe the chroma key cannot cut cleanly. Re-hatch that row from the builder, or build again with a simpler description and the pixel or sticker style, which both hold a hard outline.
It is invisible, or it is a solid block
The sheet lost its transparency somewhere. Re-saving a sprite sheet in an editor that flattens alpha does this, and so does converting it to JPEG. Download the pack again and do not re-encode it. Every sheet is checked before it can be downloaded, so a fresh pack is clean.
The folder ended up one level too deep
Some unzip tools wrap the archive in a folder of their own, which gives you pets/byte-toad/byte-toad/pet.json. Move the inner folder up one level and delete the empty wrapper. The -o and -Force flags in the commands above prevent this on a re-run.
The one-liner says curl or unzip is missing
macOS ships both. On Linux, install them from your package manager (apt install curl unzip or the equivalent). On Windows use the PowerShell line instead; it needs nothing extra.
Nothing renders inside tmux
Pets are not supported under tmux. Run the CLI in a plain terminal window to see them. The same goes for most multiplexers and for terminals without image support. That is a limit of the host, not of the pack.
I want to edit the sprite sheet myself
Go ahead. Keep it at 1536 by 1872, keep the row order, and make sure every unused cell is fully transparent with zero RGB. That last one catches people out: some editors leave colour data behind alpha and the validator rejects it. Row order is idle, run right, run left, waving, jumping, failed, waiting, working, review.
Nothing installed yet?
The gallery has a few dozen, each with an Install button. Or describe your own and it is hatched by the next morning.