How to DIY Your Own Codex Desktop Pet

Updated 2026-07-16 · verified against the official workflow

You aren't stuck with the built-in pets in the Codex App. OpenAI left the customization door wide open: prepare one spec-compliant spritesheet and one pet.json, put them in a local folder, and any character you draw can move onto your desktop. Easier still, OpenAI also shipped a skill called hatch-pet — hand it a few reference images and it draws the whole animation set for you. This post covers both routes and ends with a real example: two capybara memes, turned into a working desktop pet.

Is this the official way?

Yes. hatch-pet lives in the curated directory of OpenAI's official skills repo, openai/skills, and the canvas spec, the 9 animation rows, and the per-row frame counts and durations are all fixed by official contract files. One thing to keep in mind: that repo is now marked as migrating, and the new skills ecosystem lives at openai/plugins — but hatch-pet itself is still installable and usable where it is.

A pet is simpler than most people expect. It's two files:

~/.codex/pets/your-pet-id/
├── pet.json          # metadata, 4 fields
└── spritesheet.webp  # 1536×1872 spritesheet (PNG works too)

We've turned the spec details (how many frames each row uses, which cells must be left transparent) into a cheat sheet: see the spritesheet spec breakdown.

Route one: hatch-pet, let the AI draw

Good for people who want a polished hand-drawn look and are already using the Codex App. You'll need the official image generation skill installed in Codex ($imagegen, usually bundled in recent versions).

1. Install: type $skill-installer hatch-pet in a Codex conversation, then restart Codex;
2. Ask: just say "hatch me a ___ pet." A text description alone is fine, or attach reference images — your company mascot, a hand-drawn sketch, even a photo of your actual pet. Styles include pixel, plush, clay, sticker and 3d-toy; leave it out and it'll infer one;
3. Let it work: hatch-pet generates a base character for you to approve, then draws the 9 animations row by row (idle, running left and right, waving, jumping, failed, waiting, working, review), assembles the 1536×1872 sheet, cuts out the background and runs the validation script;
4. Enable: the result lands directly in ~/.codex/pets/; pick it in the pet settings and you're done.

Practical advice on reference images: 1-3 at a time, full body, clean background works best. And insist that it keep "the same face and the same palette" across every animation row — that's the highest-weighted item in the official QA standard.

Route two: draw every frame in code

For people who don't want to roll the dice and want 100% control. All 91 pets on this site are generated procedurally with Python + Pillow: the body is assembled from color blocks on a small grid, each frame gets parameters per state, and the whole thing is composited into the full-size sheet. Once the drawing engine exists, a new pet takes ten lines of config. The full approach and frame-count design are written up in the DIY section of the guide.

In practice: two memes, one desktop pet

A reader sent in two capybara memes and asked whether we could make something from them. We could — and this is exactly the standard reference-image workflow. Three steps:

1. Extract features, don't trace: what we pulled from the references was a feature list — milk-tea round body, a dark oval muzzle taking up half the face, small round ears, blush, an overall lounging posture, warm brown outlines;
2. Redraw from the features: use that list to draw an original capybara on the pixel grid, all 9 animation rows (yes, even a chill capybara jumps properly);
3. Pass official validation: run validate_atlas.py from the official repo to check dimensions, frame counts and transparency. All green or it doesn't ship.

The result is Paka the Chill Capybara — preview all 9 states right on the page and download it free.

The five easiest ways to fail

• Frame counts differ per row: idle 6, waving 4, jumping 5, running and failed 8, everything else 6 — any extra cell must be entirely transparent or it won't pass validation;
• Don't jump out of the cell: the whole pet (ears and hats included) must stay inside 192×208 in every single frame;
• Keep the transparency clean: no semi-transparent drop shadows, ground shadows or speed lines, and no leftover RGB values hiding in transparent pixels;
• Folder depth: pet.json has to sit directly inside pets/pet-id/ — an extra wrapper folder from the unzip is the single most common cause of "my pet doesn't show up";
• The working row isn't running: the official spec says this row depicts "focused work," and drawing it as a leg-pumping run will be marked non-compliant.

The fuller spec table (including official per-row durations) is here.

Don't feel like building one?

We've got 91 ready to go: 50 in the Original Gallery + 41 in the Inspired Series, all passing the official validation script, all free to download and remix. Every detail page comes with a one-line PowerShell install command — thirty seconds and the capybara or the cyber cat is living on your desktop.