# 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 | Action | How | | --------------------------- | --------------------------------------------------------------------- | | Toggle the overlay | Type `/pet` in the composer | | Wake / tuck away | Settings > Appearance, use "Wake Pet" / "Tuck Away Pet" | | Wake / tuck away (keyboard) | Press `Cmd+K` (macOS) or `Ctrl+K` (Windows), run the same commands | | Select a pet | Settings > Appearance > Pets — pick a built-in pet or refresh customs | `/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": | Pet | Description (from SKILL.md) | | ----------- | -------------------------------------- | | Codex | The original Codex companion | | Dewey | A tidy duck for calm workspace days | | Fireball | Hot-path energy for fast iteration | | Rocky | A steady rock when the diff gets large | | Seedy | Small green shoots for new ideas | | Stacky | A balanced stack for deep work | | BSOD | A tiny blue-screen gremlin | | Null Signal | Quiet signal from the void | 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 ```shell $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 ```shell $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: ```shell ${CODEX_HOME:-$HOME/.codex}/pets// 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: | Attribute | Specification | | ---------------- | ---------------------------------------------- | | Atlas dimensions | 1536 x 1872 pixels | | Grid layout | 8 columns x 9 rows | | Cell size | 192 x 208 pixels | | Format | PNG or WebP, lossless | | Transparency | Required; transparent background, no artifacts | | Unused cells | Must be fully transparent | 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`: | Row | State | Frames | Purpose | | --- | ------------- | ------ | ------------------------------------ | | 0 | idle | 6 | Neutral breathing / blinking loop | | 1 | running-right | 8 | Rightward locomotion | | 2 | running-left | 8 | Leftward locomotion (often mirrored) | | 3 | waving | 4 | Greeting / attention gesture | | 4 | jumping | 5 | Anticipation, lift, peak, descent | | 5 | failed | 8 | Error / sad reaction | | 6 | waiting | 6 | Patient idle variant | | 7 | running | 6 | Generic / front-facing run | | 8 | review | 6 | Focused thinking / inspecting | ### 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: ```text 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//`. ### 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 | Issue | Source / status | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `hatch-pet` fails with "Stream disconnected…" errors | `openai/codex` #20947 — root cause: the bundled `$imagegen` system skill is not materialized at `~/.codex/skills/.system/imagegen/SKILL.md` | | `/hatch` not discoverable in the composer slash menu | `openai/codex` #20778 — skills are not slash commands; invoke with `$hatch-pet` or natural language | --- ## 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 | Claim group | Primary source | | -------------------------------------------------- | -------------------------------------------------------------------- | | Overlay behavior, controls, Settings paths | OpenAI developer docs — Codex app Settings (`developers.openai.com`) | | Red clock / green check cues, draggable overlay | PCWorld, 4 May 2026 | | Eight built-in pet names and descriptions | `openai/skills` — `skills/.curated/hatch-pet/SKILL.md` | | Atlas geometry, row map, frame counts | `openai/skills` — `codex-pet-contract.md`, `animation-rows.md` | | Pipeline, scripts, delegation, acceptance criteria | `openai/skills` — `hatch-pet/SKILL.md` | | Known issues | `openai/codex` issues #20947, #20778 | | Launch date, super-app framing, config import | TestingCatalog, 1 May 2026 | | Contest, IP/moderation concerns, Clippy variants | Engadget, Digital Trends, May 2026 | | Super-app consolidation intent | Wikipedia — "OpenAI Codex (AI agent)" |