hatch-pet: OpenAI's skill for making a custom Codex pet
hatch-pet is OpenAI's Codex agent skill that turns your character art or idea into a custom animated Codex pet.
- Installs
- 3.4K
- on skills.sh
- Stars
- 28.4K
- on GitHub
- Files
- 13
- besides SKILL.md
- Updated
- Oct 2026
- last repo commit
hatch-pet is OpenAI's Codex agent skill that turns your character art or idea into a custom animated Codex pet. A Codex pet is a small companion in the ChatGPT desktop app and the Codex CLI that shows whether a chat is running, needs input, is ready or is blocked. Describe a character, give a brand name or attach pictures, and the skill generates the art, builds the animation sheet and saves the pet. Pets only show up in Codex, and a good one can take a few tries.
Good for
- Codex users who want their own pet instead of a built-in one
- Designers and illustrators who already have character art to animate
- Teams that want a mascot pet from a company or brand name
- People who run several agents and want a glanceable status signal
Install hatch-pet
Codex
- 1
Open Settings > Pets in the ChatGPT desktop app and select Create pet.
- 2
The app installs the bundled hatch-pet skill, reloads skills and opens a new chat.
- 3
Describe your pet or attach art, then run it to the end.
- 4
When it finishes, select Refresh in Settings > Pets and choose your pet.
Requires Python 3 with Pillow, jq.
Pets only show in Codex, so there is no Claude Code or Cursor setup. SKILL.md runs its scripts from ~/.codex/skills/hatch-pet, which is where both methods above put the skill. The Codex CLI shows custom pets, and the IDE extension has no pet display. The openai/skills repo is marked deprecated in its README, so the desktop app route is the safer default.
From the vendor's docs. Source.
What's in the skill
When it loads
Create, repair, validate, visually QA, and package Codex-compatible animated pets and pet spritesheets from character art, generated images, company or prospect brand cues, or visual references. Use when a user wants a lightweight-worker Codex pet workflow, a non-pixel custom pet style, a prospect or company mascot pet, or a full 8x9 animated pet atlas with transparent unused cells, QA contact sheets, and pet.json packaging. This skill composes the installed $imagegen system skill for visual generation and uses bundled scripts for deterministic spritesheet assembly.
Sections in SKILL.md
- Overview
- Generation Delegation
- Storage Controls
- Brand Discovery
- Pet-Safe Styles
- Transparency And Effects
- Visible Progress Plan
- Default Workflow
- Lightweight Visual Workers
- Subagent Delegation
- Repair Workflow
- Rules
- Acceptance Criteria
Key facts
- Author
- OpenAI
- Installs on skills.sh
- 3.4K (Nov 2, 2026)
- What installs
- 14 files: SKILL.md, 8 Python scripts, 3 reference docs, Codex display metadata (agents/openai.yaml) and LICENSE.txt
- Last change to the skill
- May 12, 2026
What it includes
Looks up brand cues on the web when you give only a company name
Optional. If you give a description or pictures instead, this step is skipped.
Try: “$hatch-pet make a pet for Stripe”
Network ·
Brand discoverySets up the run folder, prompts and layout guides, and picks a name and style
Chooses a name (Sprout by default), a style preset and a background color for cutting the art out, then writes the job list.
Files ·
prepare_pet_run.pyGenerates the main look of your pet with Codex's image skill
One picture of the pet that every animation row is drawn from.
Network ·
Base imageGenerates one strip per state: idle, running, waving, jumping and more
Up to 10 image jobs in total, one base plus nine rows, with at most two running at once.
Network ·
Nine animation rowsMirrors the running-right row into running-left
Used only after the right-facing row looks safe to flip.
Files ·
derive_running_left_from_running_right.pyCuts each strip into 192x208 pixel frames
Has a stable-slots mode that stops the pet from changing size between frames.
Files ·
extract_strip_frames.pyFlags frames with stray edge pixels, empty frames or leftover background color
Writes a review file that the visual check reads.
Read ·
inspect_frames.pyBuilds the 1536x1872 sprite sheet as PNG and WebP
A grid of 8 columns by 9 rows, one row per pet state.
Files ·
compose_atlas.pyChecks the sheet size, grid and empty cells
Writes a validation report next to the finished sheet.
Read ·
validate_atlas.pyMakes one labeled overview image of every frame for review
Lets you and the skill spot drift in the pet's look.
Files ·
make_contact_sheet.pyMakes a GIF preview for each pet state
Saved in a previews folder so you can watch each animation.
Files ·
render_animation_previews.pyReviews previews for look drift, wrong direction and popping, then redraws only the bad ro
You do not have to restart the whole pet to fix one animation.
Try: “$hatch-pet repair the waving row of my pet Sprout”
Network ·
Visual check and repairSaves pet.json and spritesheet.webp into your Codex pets folder, then cleans up
Pick the pet afterwards in Settings > Pets.
Files ·
Package
From the official docs
Permissions
Low risk
hatch-pet only runs local image scripts and saves files into your Codex folder, but it deletes its own working files and can search the web when you give only a brand name. The skills.sh audits show Gen Agent Trust Hub Pass, Socket Pass and Snyk Warn, and no security advisories are listed for the repo.
What it can do
- Read your data
- Create and change things
- Delete things
- Read-only mode
Watch out for
Brand names trigger a web search
Snyk rates this Warn (medium) because the skill reads outside web pages to find brand cues. Give a description or pictures instead if you want no web search. skills.sh
It deletes its own generated images and run files
After copying each picked image it removes the original from ~/.codex/generated_images, and it clears working files after checks. Ask to keep debug files if you want them. github.com
Create pet has overwritten an installed hatch-pet folder
Users report the app replacing a hatch-pet folder installed another way, and deleting it on some Windows builds. Back up the folder before you click Create pet. github.com
Failed image attempts can still use your quota
A user reports that failed image generation on Windows still counted against usage. Watch your usage if generation keeps failing. github.com
Runs eight local Python scripts
They use Pillow to cut frames, build the sheet and make previews, and contain no network calls or subprocesses. Python with Pillow and jq must be on your machine. github.com
Security advisories
No published security advisories as of Nov 2, 2026.
Technical details
| Turning on read-only | No read-only mode. The skill writes a run folder and the finished pet, and deletes its own intermediate files after QA unless you ask to keep debug files. |
|---|---|
| Talks to | Image generation through Codex's built-in $imagegen tool. Web search for brand cues, only when you give a brand name instead of a description or pictures. api.openai.com, only if you ask for the optional OPENAI_API_KEY fallback |
| Sign-in and keys | No key by default. The optional image fallback reads OPENAI_API_KEY from your environment and runs only if you ask for it. |
| Data retention | Built-in image generation stores image bytes in your Codex session log, and deleting the files later does not shrink it. |
| Scopes |
|
What people say
People like having a pet that shows what their agents are doing, and complain that a usable pet takes several tries.
What people like
- A pet gives a visible signal of what your agents are doing and when they need attention.
- The skill shows labeled previews and checks the sheet before it saves the pet.
Common complaints
- Getting a usable pet took several tries for people on the OpenAI forum.
- Pets stay on the machine where they were made and do not sync to ChatGPT web.
- Create pet fails for some Windows setups and has overwritten an installed hatch-pet folder.
In their words
“I like the idea of a visual representation and communicator of what my agents are doing and when they need attention.”wellandravenForumAug 2026
“For some reason took more than 3 tries to use the hatch-pet skill to get her done. Wish this would be cross-environment, she’s only on windows currently.”DysTopiaForumJul 2026
“Creating Sentinel was fun, but it also took several iterations: refining the shape, improving symmetry, keeping the design visible in dark mode, and validating the final sprite sheet.”FarturGitHub issueJul 2026
“However, after restarting Codex and using the "Create Pet" workflow, the hatch-pet skill directory is unexpectedly overwritten.”can340236-alt
Examples
The default prompt OpenAI ships with the skill
Use $hatch-pet to create a Codex-compatible animated pet in any pet-safe style from a concept, company brand, or reference image.
SourceText-only pet: no reference picture, so the skill draws a base image first
$hatch-pet a sleepy red panda with a tiny laptop, plush style
Mascot pet from just a company name, using a web search for brand cues
$hatch-pet make a pet for Stripe
Fix one broken animation row instead of redoing the whole sheet
$hatch-pet repair the waving row of my pet Sprout
Workaround a user posted when Create pet would not start
Use the https://github.com/openai/skills/tree/main/skills/.curated/hatch-pet skill to generate a pet for me: <Pet Description>
Source
Questions
How do I install hatch-pet?
Use the install box above. In the ChatGPT desktop app, open Settings > Pets and select Create pet, which installs the skill for you. Or run the install command inside Codex and restart Codex if the skill does not appear.
How do I make and use a custom Codex pet?
Run Create pet or type $hatch-pet in a Codex chat, then describe the character or attach art. When the task finishes, open Settings > Pets, select Refresh and choose your pet. The skill saves it as pet.json and spritesheet.webp in ~/.codex/pets/<pet>/. Type /pet to show or hide it.
Does hatch-pet work in Claude Code?
No. No source documents it. The skill calls Codex's own image skill and saves to ~/.codex/pets, and only Codex shows pets. If you need a Claude Code extra, this is not it.
Does it work in the Codex CLI, the IDE extension and ChatGPT web?
The CLI can show custom pets, in iTerm2 3.6 or newer or a terminal with Kitty graphics or Sixel, and not inside tmux or Zellij. The IDE extension has no pet picker. Pets made in the desktop app do not sync to ChatGPT web, where you can only upload a finished 1536 x 1872 sprite sheet.
Do I need an OpenAI API key for hatch-pet?
No. The default path uses Codex's built-in image tool, which needs no key. Only the optional fallback needs OPENAI_API_KEY, and it runs only if you ask for it.
Is hatch-pet safe?
Mostly. Its scripts only process images on your machine, and it writes to a run folder and ~/.codex/pets. skills.sh shows Gen Agent Trust Hub Pass, Socket Pass and Snyk Warn, where the warning is about web search for brand cues.
Is hatch-pet deprecated?
The openai/skills README says that repository is deprecated and points to openai/plugins, where hatch-pet is not listed. The skill still works, and the desktop app installs its own copy through Create pet.
Why does Create pet say Unable to start pet creation?
On Windows this has two reported causes. With the WSL agent environment, switch the agent environment to Windows, fully restart the app and try again. Microsoft Store builds also fail, and that issue is still open. Another report says the bundled skill was missing, and asking Codex to use the hatch-pet skill from its GitHub URL worked around it.
Why did Create pet delete or overwrite my hatch-pet folder?
Users report that Create pet replaces a hatch-pet folder installed with the skill installer, and on some Windows builds deletes it. Back up the folder first and reinstall the skill if it disappears.
Why does Codex disconnect while making my pet?
A report on the Codex CLI says the stream disconnects when the workflow reaches image generation. Restart and run it again, and ask Codex to repair only the failing row instead of starting over. The issue is still open.
Information
updated Nov 2, 2026
- Repository
- openai/skills
- Folder
skills/.curated/hatch-pet
Sources
Docs, issue trackers and discussions this page is built from.
Show all 31Hide
- Pets · learn.chatgpt.com
- openai/skills README · github.com
- hatch-pet SKILL.md · github.com
- github.com · github.com
- github.com · github.com
- hatch-pet on skills.sh · skills.sh
- github.com · github.com
- github.com · github.com
- github.com · github.com
- github.com · github.com
- github.com · github.com
- github.com · github.com
- github.com · github.com
- github.com · github.com
- github.com · github.com
- github.com · github.com
- github.com · github.com
- github.com · github.com
- imagegen SKILL.md · github.com
- Create pet with WSL agent environment · github.com
- Create pet on Microsoft Store builds · github.com
- Create pet shows Unable to start pet creation · github.com
- Hatch Pet skill directory is overwritten after using Create Pet workflow · github.com
- Codex CLI stream disconnects when running hatch-pet imagen workflow · github.com
- Gen Agent Trust Hub audit · skills.sh
- Socket audit · skills.sh
- Snyk audit · skills.sh
- Image generation unavailable in the Windows app · github.com
- openai/skills security advisories · github.com
- Show us your custom Codex Pet · community.openai.com
- openai.yaml · github.com