PetGen

Codex Pet Spritesheet Specification

The exact spritesheet grid, nine animation states, and pet.json contract for building a pixel companion that runs inside OpenAI Codex.

Overview

A Codex pet is two files that live in your ~/.codex/pets// folder: a single transparent spritesheet image and a pet.json metadata file. Codex reads the folder at startup, slices the spritesheet into frames by a fixed grid, and plays the matching animation as your coding companion.

Total
1536 × 1872 px
Grid
8 cols × 9 rows
Cell
192 × 208 px

Spritesheet Layout

The spritesheet is one 1536×1872 px transparent image laid out as an 8-column by 9-row grid. Each of the 72 cells is a single animation frame measuring 192×208 px. Rows map top-to-bottom to the nine animation states; columns are the frames within each state.

1
2
3
4
5
6
7
8
idle
1
2
3
4
5
6
7
8
running-right
1
2
3
4
5
6
7
8
running-left
1
2
3
4
5
6
7
8
waving
1
2
3
4
5
6
7
8
jumping
1
2
3
4
5
6
7
8
failed
1
2
3
4
5
6
7
8
waiting
1
2
3
4
5
6
7
8
running
1
2
3
4
5
6
7
8
review
1
2
3
4
5
6
7
8

Columns → frames 1–8 · Rows → animation states (top to bottom).

Animation States

Nine animation states make up the spritesheet, one per row. The frame count below is the source of truth that <code>pet.json</code> and the generator must agree on.

#KeyLabelFrames
1idleIdle6
2running-rightRun Right8
3running-leftRun Left8
4wavingWaving4
5jumpingJumping5
6failedFailed8
7waitingWaiting6
8runningRunning6
9reviewReview6

pet.json

Place a <code>pet.json</code> next to the spritesheet. It carries four fields:

pet.json
1{
2  "id": "pet_abc123",
3  "displayName": "Pixel Companion",
4  "description": "A cheerful pixel-art pet for OpenAI Codex.",
5  "spritesheetPath": "spritesheet.webp"
6}
  • idA stable unique identifier for the pet (used for caching and future updates).
  • displayNameThe human-readable name shown in Codex and the pet picker.
  • descriptionA short sentence describing the pet, shown as a tooltip or in listings.
  • spritesheetPathPath to the spritesheet image, relative to pet.json (usually spritesheet.webp).

Install

Extract the downloaded ZIP, then copy the pet folder into your Codex pets directory and fully restart Codex.

macOS — Terminal
1mkdir -p ~/.codex/pets/my-pixel-pet
2unzip -o my-pixel-pet.zip -d ~/.codex/pets/my-pixel-pet
Windows — PowerShell
1New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\pets\my-pixel-pet"
2Expand-Archive -Path "my-pixel-pet.zip" -DestinationPath "$env:USERPROFILE\.codex\pets\my-pixel-pet" -Force

Validate

Before shipping a pet, confirm these three things:

  • Spritesheet is exactly 1536 × 1872 px (8 columns × 9 rows, 192 × 208 px cells).
  • All nine animation states are present and in the correct row order with their expected frame counts.
  • pet.json defines all four fields: id, displayName, description, spritesheetPath.