Set up · Codex

Your buddy as a Codex pet

A Block Buddy is a face for your agent, drawn from its name. Codex shows a pet: a small animated companion that reacts while Codex runs, waits for you or gets stuck. A pet is a sprite sheet of the tile. Ours isn't built yet; here's what works today.

A pet floats beside the Codex desktop app, sits in ChatGPT Work chats on the web, and runs in the Codex CLI.

Get the files

Drawn in your browser from the name above. Nothing is uploaded anywhere.

Reference picturebrass-otto-tile-512.png512 × 512 PNG, transparent corners. For Codex's Create pet, today.

Pet sheetYour exact buddy as a Codex pet: a 1536 × 1872 sprite sheet and its pet.json, every row drawn from your buddy's own moves. Coming soon.

Make a pet today

Download the Reference picture.
In the Codex desktop app, open Settings → Pets → Create pet, and attach the PNG.
Ask: "Make a pet from this image. Keep the shapes, colours and eyes exactly."
Pick the new pet in Settings → Pets, then type /pet to wake it.

Codex redraws the picture with image generation, so today's pet is a cousin of your buddy, not a pixel-exact copy. Our pet sheet will be the real thing.

When our pet sheet ships

Desktop app or CLI: put pet.json and spritesheet.webp in ~/.codex/pets/brass-otto/. Then Settings → Pets → Refresh, and choose your buddy.
On the web: Settings → Personalization → Pet → Upload pet, and pick the sheet.
In the Codex CLI: /pets brass-otto. It needs iTerm2 3.6+, Kitty graphics or Sixel, and doesn't run inside tmux or Zellij.

For agents

Codex picks the pet's row from its own status: running, needs input, ready or blocked. An agent can't call a row directly. It can install a pet by writing two files.

Instructions

platform: codex pets (Codex desktop app, ChatGPT web Work chats, Codex CLI; not the IDE extension)
crop:     the tile, whole, centred in transparent 192 x 208 cells
variant:  tile (transparent), drawn frame by frame into a pet sheet
file:     brass-otto-tile-512.png
today:    the reference for Settings > Pets > Create pet (an AI redraw)
sheet:    spritesheet.webp + pet.json (ours: not built yet)
format:   WebP or PNG, exactly 1536 x 1872, 8 columns x 9 rows, transparent; web upload up to 20 MiB
path:     ${CODEX_HOME:-$HOME/.codex}/pets/<id>/{pet.json, spritesheet.webp}
pet.json: {"id", "displayName", "description", "spritesheetPath"}
rows:     idle 6 · running-right 8 · running-left 8 · waving 4 · jumping 5 · failed 8 · waiting 6 · running 6 · review 6
map:      idle > idle · running > working · review > thinking · waiting > needs-you · failed > error · waving > speaking · jumping > glad
buddy:    Brass Otto
hash:     0x4f7857573d121112474507868c95e98e2cbb66d73cc61e786482793f28ed9bb0
checked:  2026-10-21

pet.json

{"id": "brass-otto", "displayName": "Brass Otto", "description": "A Block Buddy.", "spritesheetPath": "spritesheet.webp"}

Limits

Format	A WebP or PNG sprite sheet, plus pet.json
Max size	Web upload: 20 MiB
Dimensions	Exactly 1536 × 1872: 8 × 9 cells of 192 × 208
Crop	None: the tile, whole, on transparent
Animation	Yes, that's the point. Reduced motion shows a still frame.
Who can set it	You, in Settings, or by writing the files. Not in the IDE extension.
Per-mode faces	Yes, a row per status, chosen by Codex. Which row plays for "ready" isn't documented unverified

Last checked 2026-10-21 against Pets, the pet contract and animation rows. Pets change fast; we re-check this page monthly. If a step is wrong, the platform's own docs win.