Codex Pet — Technical Reference

1. What Codex Pet Is

Codex Pets are optional animated companions built into the OpenAI Codex desktop app. They render as a floating overlay that stays on top of every other window, even when Codex itself is minimized, so the agent’s activity is visible while you work in other applications.

A pet is a passive status surface with one active capability: if a pet shows a message while a task is running, clicking it opens a reply path back to the agent, turning the indicator into a small two-way channel.

The feature shipped in a Codex desktop app update around 1 May 2026 (announced via OpenAI’s developer channels and dated by TestingCatalog to 1 May 2026), bundled in the same release as configuration auto-import from other tools.

Platform: Windows and macOS desktop app only. The Codex CLI has no pet feature; third-party terminal “buddies” exist for CLI-based agents but are not part of Codex.

2. What the Overlay Shows

The overlay keeps active Codex work visible while you use other apps. Per OpenAI’s official Codex app settings documentation, it:

• shows the active thread,
• reflects whether Codex is running, waiting for input, or ready for review,
• pairs that state with a short progress prompt so you can glance at what changed without reopening the thread.

First-party reporting (PCWorld, May 2026) adds two concrete visual cues observed in the shipped product:

• a small red clock face in the thought bubble when the agent is waiting for your approval before executing a command,
• a green checkmark when the agent has finished a task and is ready for a new prompt.

The pet stays above other desktop windows and is draggable to any screen position.

3. Controls

/pet is a real composer command. Note: hatch-pet is a skill, not a slash command — see Section 5.3. An open issue (openai/codex #20778) documents that typing /hatch in the composer slash menu shows “No command”; skills are invoked with $hatch-pet or natural language, not via the slash menu.

4. Built-in Pets

Eight pets ship with the app in a deliberately cute pixel-art style. The canonical hatch-pet SKILL.md lists all eight by name as the “good built-in style examples”:

PCWorld independently confirms four of these names in the shipped app: the default blue “Codex”, the duck “Dewey”, “Rocky”, and “BSOD”.

5. The hatch-pet Skill — Custom Pets

hatch-pet is a curated OpenAI skill (in the openai/skills repository, under skills/.curated/hatch-pet/) for creating, repairing, validating, previewing, and packaging Codex-compatible animated pet spritesheets. License: Apache-2.0.

5.1 Installation

$skill-installer hatch-pet

Run inside the Codex app, not a system terminal. Then reload skills: press Cmd+K / Ctrl+K, choose Force Reload Skills.

5.2 Invocation

$hatch-pet create a new pet inspired by my recent projects

A pet can be created from a text concept, one or more reference images, or both. Per the SKILL.md: if you omit a pet name, the skill infers one from the concept or reference filenames; if you omit a description, it infers one. If you provide no reference images, the skill generates the base pet from text first and uses that base as the canonical reference for every animation row.

This is sprite generation, not poster generation. Describe what to carry across: color, shape, expression, accessory, character. Detailed or realistic reference art is deliberately simplified into the house pixel-pet style.

5.3 What the skill is — and is not

hatch-pet is a skill, invoked via $hatch-pet or natural language. It is not a composer slash command. Some reporting describes a /hatch command; the canonical behavior is the $-prefixed skill invocation.

6. Custom Pet Package Format

A finished custom pet is two files, staged together:

${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
  pet.json
  spritesheet.webp

CODEX_HOME overrides the default ~/.codex location.

6.1 The Codex Pet Contract — atlas geometry

Verified against references/codex-pet-contract.md and references/animation-rows.md in the openai/skills repository:

The atlas is consumed by the Codex app’s webview, which switches animation state based on what is happening in the agent’s thread.

6.2 Animation row map

Each of the 9 rows is one agent state with a fixed frame count. Verified against references/animation-rows.md:

6.3 Style and effects constraints

The SKILL.md enforces a strict house style and transparency contract:

• House style: compact chibi proportions, chunky readable silhouettes, thick 1–2 px dark outlines, visible stepped/pixel edges, limited palettes, flat cel shading, simple expressive faces, tiny limbs. No polished illustration, painterly rendering, anime key art, 3D rendering, glossy icon treatment, realistic texture, soft gradients, or high-detail antialiasing.
• Effects must be attached: any effect must be state-relevant, physically touching or overlapping the pet silhouette, inside the same frame slot, opaque and hard-edged, and small enough to read at 192x208. Allowed examples: a tear touching the face, a smoke puff touching the head, tiny stars overlapping the pet.
• Forbidden by default: speed lines, motion arcs, afterimages, blur, detached sparkles, floating icons, cast/contact/drop shadows, floor shadows, glow, halo, aura, text, labels, speech/thought bubbles, UI panels, checkerboard transparency, white or black backgrounds, scenery, chroma-key-adjacent colors, stray pixels, cropped body parts, or poses that cross into a neighboring frame slot.
• State-specific: waving shows the wave through paw pose only; jumping shows vertical motion through body position only; running rows show locomotion through body/limb/prop movement only.

7. The hatch-pet Generation Pipeline

The skill combines AI image generation (delegated) with deterministic Python scripts (assembly and QA). It explicitly forbids synthesizing pet visuals with local code, Pillow, SVG, canvas, or HTML/CSS as a substitute for image generation.

7.1 Generation delegation

All normal visual generation is delegated to the $imagegen system skill at ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md. The skill does not call the Image API directly on the normal path.

A normal pet run expects up to 10 image-generation jobs: 1 base pet plus 9 row-strip jobs. The only exception is running-left, which may be derived by mirroring running-right after that row has been generated, visually inspected, and explicitly approved as safe to mirror.

Only the base job may be prompt-only. Every row-strip job must attach grounding images, including the canonical base reference created after the base job is recorded. A row generated without grounding images is treated as invalid.

7.2 Default workflow

1. Prepare. prepare_pet_run.py creates the run folder, infers name / description / chroma key as needed, writes pet_request.json, base and row prompts, the imagegen-jobs.json manifest, and 9 per-state layout-guide images under references/layout-guides/.
2. Inspect jobs. pet_job_status.py reports which jobs in the manifest are ready, blocked, or complete.
3. Generate base. The base job runs first via $imagegen. After it is recorded, record_imagegen_result.py writes decoded/base.png and references/canonical-base.png.
4. Generate rows. Each row strip is generated via $imagegen, grounded on the canonical base plus the matching layout guide. Row-strip generation is delegated to subagents by default (one row job per subagent); the parent agent alone owns the manifest, recording, mirroring, finalization, and packaging.
5. Mirror running-left (optional). derive_running_left_from_running_right.py mirrors running-right frame-by-frame, only with --confirm-appropriate-mirror and a decision note, and only when the design is symmetric enough that flipping preserves identity, prop placement, handedness, markings, lighting, and direction semantics.
6. Finalize. finalize_pet_run.py extracts frames, removes chroma key, composes the 8x9 atlas, validates geometry, builds the QA contact sheet and preview videos, verifies job hashes against the manifest, and rejects any locally synthesized rows.

Expected run-directory layout after finalize:

run/
  pet_request.json
  imagegen-jobs.json
  prompts/
  decoded/
  frames/frames-manifest.json
  final/spritesheet.png
  final/spritesheet.webp
  final/validation.json
  qa/contact-sheet.png
  qa/review.json
  qa/run-summary.json
  qa/videos/*.mp4

The packaged pet (pet.json + spritesheet.webp) is written outside the run directory, to ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/.

7.3 Frame extraction

extract_strip_frames.py removes the chroma-key background (default green #00FF00, but the actual key is stored per-run in pet_request.json), uses connected-component analysis to find individual sprites in a strip, then resizes and centers each sprite into a 192x208 cell.

7.4 Repair workflow

If finalization stops on a row QA failure, queue_pet_repairs.py reopens the failed row jobs. Repair targets the smallest failing scope — a single frame, then a single row, then the full atlas — never the whole sheet by default. Repairs reuse the canonical base, original references, contact sheet, and the exact failure note as grounding context.

7.5 Secondary fallback

generate_pet_images.py calls the OpenAI Images API directly and requires OPENAI_API_KEY. It is a secondary fallback, used only when $imagegen is unavailable, and only after explaining why the normal path cannot be used.

8. Acceptance Criteria

A pet is considered “hatched” only when, per the SKILL.md acceptance criteria:

• the final atlas is PNG or WebP, exactly 1536x1872, transparent-capable, built on 192x208 cells;
• used cells are non-empty and unused cells are fully transparent;
• the atlas follows the row/frame counts in references/animation-rows.md;
• contact sheet and preview videos have been produced (unless explicitly skipped);
• qa/review.json has no errors;
• a row-by-row review confirms the animation cycles are complete enough for the app;
• pet.json and spritesheet.webp are staged together in the pet folder.

Deterministic validation is necessary but not sufficient: visual identity drift across rows (a row that looks like a related-but-different pet) is a blocker even when qa/review.json and final/validation.json report no errors.

9. Known Issues

10. Ecosystem (Third-Party — Not Official OpenAI)

A community ecosystem appeared within hours of launch. The items below are independent open-source projects, not OpenAI products. Their package formats mirror the Codex Pet contract but their hosting, licensing, and behavior are set by their maintainers — verify each before depending on it.

• Petdex — OpenAI’s docs refer to the official community gallery concept; a separate independent project also uses the “Petdex” name. The naming overlap is a real source of confusion; confirm which “Petdex” a link points to before using it.
• codexpets/codex-pets (GitHub, MIT) — a system-wide, multi-agent pixel pet that reacts to several agents at once (Codex, Claude Code, Cursor). Explicitly not the official Codex Pets; it states it observes events, not file or message content, with zero telemetry. Independent of OpenAI.
• Other community galleries and installers exist (referenced in the source notes this document was compiled from). Their availability, package contents, and domain ownership were [UNVERIFIED] at compile time and are therefore not asserted here. Treat any gallery domain as unverified until checked directly.

The community response also surfaced two recurring concerns flagged by observers: intellectual-property risk when users generate copyrighted characters (Engadget documented user-made Microsoft Clippy variants), and moderation load on community galleries that allow sharing user-created assets.

11. Contest

OpenAI ran a limited-time contest: creators of 10 favorite custom pets receive 30 days of ChatGPT Pro. Confirmed by Engadget and Digital Trends; the entry window is likely closed by now (compile date 2026-05-26) — verify current status if relevant.

12. Strategic Context

Reporting (TestingCatalog) reads the Pets release, bundled with config auto-import, as part of a broader pattern: OpenAI repositioning Codex from a coding command center toward a fuller desktop “super-app” surface, where personality and stickiness are treated alongside raw capability. Wikipedia’s Codex entry separately notes an announced intent to combine the ChatGPT app, Codex, and ChatGPT Atlas into a single desktop super-app. This is analysis and announced intent, not a shipped specification.

13. Source Map