Pets / Guide

One sheet.
Nine states. Zero setup.

Every pet ships as a single spritesheet that drops straight into the Codex desktop app — and slices cleanly in any engine: one row per animation state, 8 cells per row.

Install into Codex

Codex (OpenAI's coding agent app) shows a pet overlay that reflects what the agent is doing. These pets plug in with no extra config:

1.Download the “Install in Codex” zip from any pet page and unzip it.
2.Copy pet.json and spritesheet.webp into ~/.codex/pets/<name>/ (create the folder if needed).
3.Restart Codex and pick the pet under Settings → Appearance → Pets.
4.Run /pet in any thread to wake it — it keeps working as a floating overlay while you use other apps.

~/.codex/pets/shibe/
├── pet.json            { id, displayName, description,
│                         spritesheetPath: "spritesheet.webp" }
└── spritesheet.webp    1536 × 1872 · 8 × 9 · 192 × 208 per cell

The nine states match the Codex app contract 1:1 (idle, running, running-left, running-right, jumping, waving, failed, waiting, review), so behavior is identical to built-in pets.

Sheet anatomy

Each sheet is 1536×1872 px: 8 columns × 9 rows, every cell a 192×208 px frame with a transparent background. Row 0 is always the first state in the list on each pet page; read frames left to right. If a state has fewer than 8 frames, the remaining cells in that row are empty — loop only the frames the pet page lists.

sheet.webp  1536 × 1872
┌──────── 8 columns ────────┐
│ f0  f1  f2  f3  f4  …  f7 │ ← row 0 · idle
│ f0  f1  f2  f3  ·   ·   · │ ← row 1 · next state
│ …                         │
└──────── 9 rows ───────────┘  192 × 208 per cell

The bundle zip also includes a README.txt with the exact row index and frame count for every state — no guessing.

Animation states

All 433 pets share the same nine states, so you can swap sprites without touching your state machine.

idle

Default resting loop. Use when the pet stands still beside the player.

running

Forward movement. Side-facing run cycle for following the player.

running-left

Explicit leftward run, when your engine doesn't mirror frames.

running-right

Explicit rightward run, when your engine doesn't mirror frames.

jumping

Airborne pose loop. Play while the pet is mid-jump or falling.

waving

Greeting emote. Trigger on spawn, on level-up, or on interaction.

failed

Negative reaction — miss, collision, or a failed action.

waiting

Long-idle variant. Switch to it after N seconds of no input.

review

Showcase loop used during QA. Usable as an alternate idle.

Engine setup

Godot 4

Import the sheet, build AtlasTexture frames with region (col×192, row×208, 192, 208), and push them into an AnimatedSprite2D per state.

var frames := SpriteFrames.new()
for col in range(FRAME_COUNT[idle]):
    var tex := AtlasTexture.new()
    tex.atlas = sheet
    tex.region = Rect2(col * 192, ROW[idle] * 208, 192, 208)
    frames.add_frame("idle", tex)

Unity

Select the texture in the Project window, set Sprite Mode to Multiple, open the Sprite Editor and choose Grid By Cell Size with 192 × 208. Each row becomes one animation clip.

Phaser 3

// rows differ per state — see the pet page for row indices
this.anims.create({
  key: "idle",
  frames: this.anims.generateFrameNumbers("pet-sheet", {
    start: ROW.idle * 8, end: ROW.idle * 8 + FRAMES.idle - 1,
  }),
  frameRate: 10, repeat: -1,
});

Pure CSS

Use one GIF per state if you only need a looping preview:

<img src="https://r2.favori.dev/codexpet/pets/black-kitty/gif/idle.gif"
     alt="Black Kitty idling" width="192" height="208" />

Good to know

Frames are drawn at 192×208 — scale down by whole numbers (96×104, 48×52) with nearest-neighbor filtering to keep pixels crisp.
running-left / running-right are real cycles, not mirrors — use whichever matches your movement axis, or flip one of them to save memory.
Prefer the WEBP sheet in web projects (smaller download); use PNG if your pipeline can't decode WEBP.
Every bundle's README.txt lists row indices and frame counts — the same numbers shown on each pet page.

Browse pets Read license