Codex Desktop Pet Guide
What it is
Pets is a feature of the OpenAI Codex App (desktop version): a small, transparent, always-on-top window with a pixel creature living in it. It isn't decoration — the animation state is tied to what Codex is doing:
- while Codex is generating code, the pet plays "working" and shakes with effort;
- when Codex stops and waits for your input, it switches to "waiting for you" and looks up at you;
- on success it leaps to celebrate; on failure it wilts on the spot and breaks into a cold sweat.
No window switching required — one glance at the pet tells you whether it's time to go back to the terminal.
Getting your first pet running
- Make sure you're on the Codex App desktop version (not the plain CLI), and enable Pets in the settings;
- Download any pet's
.pet.zipfrom the gallery; - Extract it into the pets folder — one folder per pet:
# macOS / Linux
~/.codex/pets/<pet-id>/
├── pet.json
└── spritesheet.webp (PNG works too)
# Windows
%USERPROFILE%\.codex\pets\<pet-id>\Once it's in place, the new pet shows up in the Codex App's pet picker. If it doesn't appear, restart the Codex App.
The spritesheet spec (official)
Every animation a pet has lives in a single image: 1536×1872 pixels, PNG or WebP, transparent background, sliced into 8 columns × 9 rows of 192×208 cells. Note that each row uses a different number of frames (this is spelled out in the official contract, animation-rows.md), and any unused cell in a row must stay fully transparent. Top to bottom:
| Row | State ID | Name | Frames used | Loop duration | When it plays |
|---|---|---|---|---|---|
| 0 | idle | Idle | 6 | 1100ms | Breathing quietly, blinking now and then |
| 1 | running-right | Running right | 8 | 1060ms | Codex sent it off to work on the right |
| 2 | running-left | Running left | 8 | 1060ms | On its way back |
| 3 | waving | Waving | 4 | 700ms | A quick hello before the task kicks off |
| 4 | jumping | Jumping | 5 | 840ms | Task done — a happy little leap |
| 5 | failed | Failed | 8 | 1220ms | Something broke; it wilts in place and breaks into a cold sweat |
| 6 | waiting | Waiting for you | 6 | 1010ms | Codex has paused for input, and it's staring right at you |
| 7 | running | Working | 6 | 820ms | Codex is generating code — it's shaking with effort |
| 8 | review | Review | 6 | 1030ms | Eyes narrowed, scanning your code left to right |
A few rules that trip people up:
- the whole pet must fit inside its 192×208 cell — even at the peak of a jump, nothing may spill out;
- transparent means truly transparent: unused pixels must have alpha 0 with no leftover RGB values, and you can't draw semi-transparent drop shadows, ground shadows, speed lines or other "detached effects" (the official validate_atlas.py checks pixel by pixel);
- don't draw readable text or logos on the pet;
- keep details chunky — the display size is tiny, and a one- or two-pixel pattern simply won't be visible.
What pet.json looks like
{
"id": "momo",
"displayName": "Momo",
"description": "A round cream-orange cat.",
"spritesheetPath": "spritesheet.webp"
}Four fields is all it takes. Use lowercase alphanumerics for id and keep it identical to the folder name; spritesheetPath is relative to pet.json.
Making one yourself
Option one: let the AI draw it (the official route). OpenAI ships a hatch-pet skill in openai/skills. Install it in Codex, describe the character you want, and it calls image generation to draw all 9 animation rows one at a time, assembles them into a spec-compliant spritesheet, and drops the result straight into ~/.codex/pets/. Good if you want a polished hand-drawn feel.
Option two: draw every frame in code (our route). All 91 pets on this site are generated procedurally with Python + Pillow: the body is built out of color blocks on a 24×26 logical grid, then each frame gets parameters per state — idle is a breathing rise-and-fall plus a blink, jumping is a displacement curve through crouch, stretch, air and landing, failed is a squashed body with X eyes and a cold sweat. Finally it's assembled into the 1536×1872 sheet using each row's official frame count. Once we hit a few dozen pets we abstracted the whole thing into a config-driven system: body shape, palette, ears, tail, glasses and scarf are all parameters, and adding a new pet takes about ten lines of config.
Both routes produce the same thing: one compliant spritesheet and one pet.json. When you're done, drop the folder into the pets directory and it runs.
FAQ
My pet won't move, or doesn't show up? Check the folder depth first — pet.json has to sit directly inside pets/<id>/, with no extra wrapper folder from the unzip. Then check that the image is exactly 1536×1872.
What's the difference between V1 and V2? What the community calls V2 adds 16 directional "look-around" frames on top of the base 9-row spec, so the pet can face your mouse. Pets built to the base 9-row spec (including ours) still work perfectly in current versions of the Codex App.
Can I modify the pets from this site? Yes. All 91 are original pixel art (the Inspired Series only references themes and genres, never copyrighted characters). Change them, share them, no attribution required.