Overview
Hatch Pet is a reusable Codex skill that turns three to five photos of one animal, plus an optional personality note, into an installable animated Codex Desktop companion. It preserves identity across software states, maps temperament to motion, validates the exact v2 atlas, repairs only failed rows, and installs with backup and checksum readback.
Inspiration
One generated pet portrait can look convincing while the same animal becomes unrecognizable as soon as it sleeps, turns left, works at a laptop, or reacts to an error. A real pet is defined by small, personal details: one asymmetric face patch, a particular eye shape, an unusual tail, and a characteristic rhythm of movement. I wanted Codex personalization to preserve those details instead of producing a generic mascot.
What it does
The user supplies three to five photos of the same animal and can add one sentence about personality. Hatch Pet treats those photos as one identity set, records stable and asymmetric traits, and converts personality into motion cadence without changing the semantics of Codex states.
It produces nine state-aware animation rows plus sixteen renderer-selected gaze directions in the exact Codex v2 8x11 atlas. The pipeline checks geometry, transparency, cropping, continuity, direction, identity, cadence, and prop contact. If one state fails, Hatch Pet regenerates and replaces only that row. A verified installer stages the package, checks decoded assets and checksums, backs up any existing pet, installs atomically, and reads the live files back.
Source photos stay local to the build run. They are not included in the final pet package, telemetry, or repository.
How I built it
I built the Build Week extensions in Codex using GPT-5.6 Sol. Codex helped convert real photo and behavior observations into explicit identity, animation, prompt, and repair contracts; separate permanent traits from state-only props; create bounded visual jobs; build deterministic atlas, validation, and installation scripts; diagnose failed rows; and add regression tests. I made the human judgment calls around recognizability, personality, motion density, privacy, and final acceptance.
The implementation combines image generation for candidate visual rows with deterministic Python and Pillow tooling for assembly, validation, packaging, and installation. Visual review is evidence-based: labeled sheets verify semantics, blind sheets verify direction, animated strips verify cadence, and independent final review checks the exact pixels that will be installed.
Challenges
The hardest problem was not generating attractive art; it was keeping identity and behavior stable under tiny UI constraints. Structural validation can pass while the pet still looks wrong. Mika's early iterations exposed a reversed left gaze, an overactive idle, and a disconnected work prop. A second pet, Snow, exposed split running tails, scale popping, a repeated look quadrant, and chroma-fringed provisional previews even after the final atlas itself was clean.
Those failures led to the core product decisions: identity and asymmetry locks, state-scoped references, a tiny-UI acceptance ladder, immutable direction evidence after final pixel changes, minimal-row repair, and separate deterministic and visual QA gates.
Accomplishments
- A reusable photo-to-pet workflow rather than a Mika-specific prompt.
- Two installable Codex v2 reference packages with nine states and sixteen directions each.
- Deterministic atlas, package, checksum, backup, rollback, and readback tooling.
- Independent visual QA that catches failures structural tests cannot see.
- A public install path and judge fast path that do not require rebuilding the example.
- Reproducible Mika installation on two macOS machines plus an independently reviewed Snow repeatability run from a separate three-photo identity set.
What I learned
For personal generative products, recognizability is a system property, not a prompt adjective. The reference set, state contract, repair scope, review evidence, and installer all contribute to whether the result still feels like the same animal. I also learned that personality should change timing and anticipation more than amplitude: a desktop companion feels alive when it is legible and restrained, not when every loop demands attention.
What's next
The immediate next step is to validate the workflow with more body plans and markings, especially dogs, rabbits, and birds, while measuring time-to-first-pet and repair count. I also want a faster preview tier before full generation, stronger automated identity comparisons, verified Windows support, and a small consent-safe gallery of community pets.
Open-source and prior-work disclosure
OpenAI published an Apache-2.0 curated hatch-pet workflow before Build Week. This submission is a meaningful extension of that baseline, not a claim of creating the original workflow during the event. The judged post-2026-07-13 work is the multi-photo real-pet identity system, personality-to-motion mapping, Codex v2 sixteen-direction output, evidence-scoped prompt and repair contracts, deterministic and independent visual QA, minimal-row repair, safe installation, and the working reference package. The repository preserves upstream attribution and separates inherited Apache-2.0 files from new MIT-licensed project material.
Testing instructions
Judges can test the packaged result without generating a new animal:
- Install
skill/hatch-petusing the README instructions. - Verify and dry-run install
examples/mikaorexamples/snow. - Install into an isolated Codex home or the local Codex pets directory.
- In Codex Desktop on macOS, use Settings → Personalization → Pets → Refresh → Select → Wake Pet.
For the full flow, upload three to five authorized photos of one animal and ask Codex: Use $hatch-pet to turn these photos into my Codex pet. Windows support is not yet claimed.
Log in or sign up for Devpost to join the conversation.