README.md

English · 简体中文

🧡 Meet Lulu

Capybara Lulu is a custom pet pack for the ChatGPT desktop app's Codex experience. Lulu breathes, blinks, opens her mouth, and waves with one paw while idle; runs when dragged; follows the pointer; and reacts when Codex is working, waiting for input, ready for review, or blocked.

The shipped pet/spritesheet.webp is an animated 8 × 11 atlas with 20 synchronized image-time phases per native state. The shared clock remains 1.60 seconds, while each directional run fits two complete 0.80-second gait cycles into that timeline so Lulu travels briskly without speeding up idle, waving, or computer work. Fifteen named visual motions are distributed across the nine real Codex triggers; the static atlas remains available for QA, editing, and reduced-motion fallback.

Lulu's behavior	What ships
🌿 Expressive idle	20 image-time phases: rest, breath, blink, mouth open/close, a single-paw wave, and a soft neutral return.
💻 Task awareness	Dedicated working, waiting, ready-for-review, and blocked reactions. Working alone contains four connected micro-cycles: typing, blink, read-screen, and alternate typing.
🐾 Physical interaction	A pointer-hover jump plus two brisk 0.80-second run cycles while Lulu is dragged left or right.
👀 Directional gaze	16 clockwise look poses at exact 22.5° intervals, with a neutral dead zone that returns to idle.
🎞️ Reproducible source	180 transparent runtime-phase PNGs, 87 native/look source PNGs, 10 GIF previews, deterministic builders, validators, and the full hatch-pet workflow.

🎬 Motion library

Every live preview uses the shipped 80 ms phase cadence. The cards below show the state name used by Codex, the trigger, and a direct route to every source frame.

🌿 Expressive idle
_{idle · 20 phases · 1.60 s}

Appears when no task status is active and the pointer is in the neutral dead zone. The image-time loop adds breathing, blink, mouth movement, a one-paw wave, and a neutral return.
Open all 20 runtime phases →

➡️ Run right
_{running-right · 20 unique phases · 2 × 0.80 s}

Appears while the floating pet is dragged toward screen-right. Two distinct two-step cycles alternate matching yellow legs and opposing arms without tail-like rear shapes.
Open all 20 runtime phases →

⬅️ Run left
_{running-left · 20 unique phases · 2 × 0.80 s}

Appears while the floating pet is dragged toward screen-left. It is a framewise mirror of the approved rightward gait, preserving phase order and timing.
Open all 20 runtime phases →

👋 Greeting
_{waving · 20 phases · 1.60 s}

Appears as the first-awake greeting after Lulu is woken.
Open all 20 runtime phases →

✨ Jump
_{jumping · 20 phases · 1.60 s}

Appears when the pointer enters or hovers over Lulu.
Open all 20 runtime phases →

🌧️ Blocked
_{failed · 20 phases · 1.60 s}

Appears when a chat fails, is blocked, or encounters a system error.
Open all 20 runtime phases →

🙋 Needs input
_{waiting · 20 phases · 1.60 s}

Appears when Codex needs approval, an answer, or another user decision.
Open all 20 runtime phases →

💻 Working
_{running · 20 unique phases · 1.60 s}

Appears while a chat is actively working. Lulu types, blinks, reads the screen, and alternates paws; both arms remain continuously attached in every phase.
Open all 20 runtime phases →

✅ Ready / review
_{review · 20 phases · 1.60 s}

Appears when a chat has completed and has unread activity ready to inspect.
Open all 20 runtime phases →

👀 Look around
_{rows 9–10 · 16 clockwise directions}

Follows the pointer while Lulu is idle, working, or greeting. The neutral/front dead zone falls back to the expressive idle.
Open all 16 direction frames →

🏃 Directional gait study

Both travel directions use 20 distinct poses split into two complete 10-phase gait cycles. Each gait takes 0.80 seconds inside the shared 1.60-second image-time clock; the leftward set is a framewise mirror, so cadence, body registration, and footfall order remain identical in either direction.

README GIFs retain transparent backgrounds so Lulu sits naturally on light and dark GitHub themes. The overview sheets use a pure white editorial canvas; all runtime-phase and native source PNGs retain their original transparency.

🖼️ Every animation frame

All 180 state phases are available as individual transparent PNGs under assets/state-phases, with 16 direction frames completing the 196-frame runtime gallery below. The 87 native/static source cells remain under assets/frames. Timing, clip ownership, and phase sources live in assets/state-phases.json and assets/frames/manifest.json.

🌿 Expressive idle timeline

The 20-phase idle loop is deliberately dense: it returns through lower transition poses rather than snapping from a raised paw to neutral. The viewer-right paw waves; the viewer-left paw stays lowered.

👀 Sprite atlas and gaze QA

🧩 Open the full 8 × 11 sprite atlas contact sheet

🧭 Open the neutral plus 16-direction gaze sheet

🐾 Install in Codex

⚡ One-command local install

Download or clone the repository, then run this from the project root:

python3 scripts/install.py

The installer:

1. copies pet/pet.json and pet/spritesheet.webp to ~/.codex/pets/capybara-lulu/;
2. backs up an existing installation under ~/.codex/backups/capybara-lulu/;
3. sets [desktop].selected-avatar-id to custom:capybara-lulu in ~/.codex/config.toml.

Use python3 scripts/install.py --no-select if you only want to stage the pet. Fully quit and reopen the ChatGPT desktop app after installation because the custom-pet list is process-cached.

🧰 Manual install

macOS and Linux:

mkdir -p ~/.codex/pets/capybara-lulu
cp pet/pet.json pet/spritesheet.webp ~/.codex/pets/capybara-lulu/

Windows PowerShell:

$target = Join-Path $HOME ".codex/pets/capybara-lulu"
New-Item -ItemType Directory -Force -Path $target | Out-Null
Copy-Item pet/pet.json, pet/spritesheet.webp -Destination $target -Force

Then open Settings → Pets, choose Refresh, and select 水豚噜噜. Use /pet, Wake Pet, or Tuck Away Pet to show or hide the floating overlay. The selected pet and its position persist across restarts.

If the current client does not select Lulu through the UI, add this to ~/.codex/config.toml and restart:

[desktop]
selected-avatar-id = "custom:capybara-lulu"

🔁 Keep task animations looping at their original speed (macOS, optional)

The desktop renderer normally plays a non-idle row three times and then falls back to idle, even when Codex is still working or waiting. This opt-in patch keeps the selected action repeating for the full lifetime of its real desktop state. It does not slow frames down, delay state changes, or keep a completed working state alive.

The patch verifies ASAR integrity and creates a timestamped backup before writing:

node hatch-pet/scripts/patch_codex_pet_playback.mjs --check /Applications/ChatGPT.app
node hatch-pet/scripts/patch_codex_pet_playback.mjs --apply /Applications/ChatGPT.app

Fully quit and reopen ChatGPT afterward. Application updates may replace the renderer patch; rerun --check after an update. The command output includes backupDir for an exact restore if needed.

⌨️ Codex CLI

In an interactive Codex CLI session, enter /pets or /pet and choose 水豚噜噜. Terminal pets require iTerm2 3.6+, Kitty graphics, or Sixel support and are unavailable inside tmux and Zellij. The IDE extension does not provide a pet picker or floating overlay.

🔗 HTTPS install link

Codex accepts pet install links with an HTTPS spritesheet URL. This repository's ready-to-share link is:

codex://pets/install?name=%E6%B0%B4%E8%B1%9A%E5%99%9C%E5%99%9C&description=Capybara%20Lulu%20desktop%20pet&imageUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fsrwang0506%2FHatchPet-CapybaraLulu%2Fmain%2Fpet%2Fspritesheet.webp&spriteVersionNumber=2

Only name, description, imageUrl, and spriteVersionNumber are accepted. imageUrl must be an absolute HTTPS URL. spriteVersionNumber=2 is the Codex 8 × 11 sprite protocol; it is not this project's release number.

⚙️ Codex and Claude Code configuration

Surface	Availability	Recommended setup
🟢 ChatGPT desktop · Codex	Native overlay	Run python3 scripts/install.py, restart the app, then select 水豚噜噜 in Settings → Pets.
🟠 Codex CLI	Native in supported terminals	Install the same local package, then use /pets in iTerm2 3.6+, Kitty graphics, or a Sixel-capable terminal.
⚪ Codex IDE extension	No pet surface	Use the desktop app or Codex CLI when you want Lulu visible as a companion.
🔵 Claude Code	Project maintenance only	Claude can edit the repository, source frames, and docs; copying pet/ into ~/.claude does not create a desktop overlay.

Claude Code can still maintain the project cleanly:

git clone https://github.com/srwang0506/HatchPet-CapybaraLulu.git
cd HatchPet-CapybaraLulu
claude

The checked-in CLAUDE.md and AGENTS.md preserve Lulu's identity and validation rules. Claude Code discovers project instructions from CLAUDE.md; its reusable skills live under ~/.claude/skills/ or .claude/skills/, as described in Anthropic's official Skills documentation.

The bundled hatch-pet workflow is the Codex authoring and QA tool used to build this pet. It calls Codex image-generation capabilities and writes the Codex pet contract, so copying it into Claude Code does not add a pet renderer or guarantee that its image-generation steps are available. A true Claude Code desktop companion would need a separate renderer and a hook bridge; this repository does not pretend that native support exists.

🧩 Optional: install the authoring skill in Codex

The repository includes the upgraded hatch-pet skill with synchronized 16–24 phase native-state packaging, 12–15 visual-motion libraries, complete-row limb QA, 9-state validation, and 16-direction validation.

mkdir -p ~/.codex/skills/hatch-pet
rsync -a hatch-pet/ ~/.codex/skills/hatch-pet/

Restart Codex or reload skills, then invoke $hatch-pet when creating or repairing a pet. This step is optional for using Lulu; the ready-to-install pet is already in pet/.

♿ Reduced motion

Official pets respect the operating system reduced-motion preference. This project's smooth state runtime uses the animated WebP image clock, which can continue even when JavaScript sprite timers are reduced. If continuous image-time motion is not appropriate, replace the installed runtime with the static QA atlas:

cp assets/spritesheet-static.webp ~/.codex/pets/capybara-lulu/spritesheet.webp

Restart the app afterward. The nine task states and 16 look directions remain available; only the synchronized image-time wrapper is removed.

🧪 Development and validation

Create an environment and rebuild the public galleries:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python scripts/build_gallery.py

Validate both the static source and the complete animated runtime:

python hatch-pet/scripts/validate_atlas.py \
  assets/spritesheet-static.webp \
  --chroma-key '#FF00FF' \
  --require-v2

python hatch-pet/scripts/validate_atlas.py \
  pet/spritesheet.webp \
  --chroma-key '#FF00FF' \
  --require-v2 \
  --allow-animated \
  --allow-transparent-rgb-residue

python hatch-pet/scripts/validate_smooth_state_webp.py \
  pet/spritesheet.webp \
  --source-atlas assets/spritesheet-static.webp \
  --phase-manifest assets/state-phases.json \
  --require-all-states \
  --min-motion-clips 12 \
  --max-motion-clips 15

python hatch-pet/scripts/measure_motion_phase_continuity.py \
  assets/state-phases/running \
  --expected-count 20 \
  --chroma-key '#FF00FF'

python hatch-pet/scripts/measure_motion_phase_continuity.py \
  assets/state-phases/running-right \
  --expected-count 20 \
  --max-area-ratio 1.26 \
  --max-centroid-shift 18 \
  --chroma-key '#FF00FF'

python hatch-pet/scripts/measure_motion_phase_continuity.py \
  assets/state-phases/running-left \
  --expected-count 20 \
  --max-area-ratio 1.26 \
  --max-centroid-shift 18 \
  --chroma-key '#FF00FF'

python -m unittest discover -s hatch-pet/tests -v

Acceptance targets:

• static and runtime atlases are exactly 1536 × 2288 RGBA;
• spriteVersionNumber remains 2;
• runtime contains 20 phases totaling 1600 ms and loops indefinitely;
• all renderer-selectable columns in all nine native rows remain phase-synchronized;
• both look rows remain render-identical to the static QA atlas;
• all 15 named visual motions remain mapped to real native triggers;
• both directional runs contain 20 distinct poses forming two complete 0.80-second gaits, and the left loop is the exact framewise mirror of the approved right loop with phase order preserved;
• both running legs use the same yellow plush palette with no dark ownership marker;
• no eyebrows, tail, detached or extra limbs, limb switching, gait reversal, or baseline pop appears.

🗂️ Repository layout

capybara-lulu/
├── assets/                 # teaser, avatar, GIFs, 267 transparent PNGs, QA sheets
├── hatch-pet/              # authoring skill, deterministic tools, references, tests
├── pet/                    # install-ready Codex package
├── scripts/                # installer and gallery builder
├── AGENTS.md               # Codex contributor constraints
├── CLAUDE.md               # Claude Code project context
├── README.md               # English documentation
└── README.zh-CN.md         # 简体中文文档

🤝 Contributing

Read CONTRIBUTING.md before changing art or timing. Visual changes must include regenerated GIFs and galleries plus deterministic validation. Security issues should follow SECURITY.md.

📜 License and names

Code, documentation, and repository assets are provided under the Apache License 2.0, subject to the rights described in NOTICE. This is an independent project and is not affiliated with OpenAI or Anthropic. Codex, ChatGPT, Claude, and Claude Code remain the property of their respective owners.