hatchery.pet
Sign in

>_  one command

Install pets from your terminal.

One command. Sign in once. Every install after is one command.

bashterminal
npx hatchery-pet install claw

What happens when you run this?

  • First time: a browser tab opens, you sign in with Google, then your terminal continues.
  • Every time after: the pet installs silently. Your token is stored at ~/.config/hatchery-pet/auth.json.
  • The pet appears at ~/.codex/pets/<slug>/ — Codex App auto-discovers it from there.

Four steps, in order.

Step one happens in the terminal. Steps two through four happen entirely in the Codex App.

01

Install a pet

Run one command in your terminal. The CLI fetches the pet and writes it to your local Codex pets directory.

bashterminal
npx hatchery-pet install claw

Writes pet.json + spritesheet.webp to ~/.codex/pets/claw/

Don’t have npm? Install Node.js first ↗

02

Open Codex App settings

Open Codex App and bring up Settings.

Keyboard

Cmd+, (mac)

Ctrl+, (Windows / Linux)

Menu

Codex → Settings

03

Pick your pet

In the sidebar, click Appearance. Scroll to Pets. Below the OpenAI built-ins, find the Custom pets section. Your installed pet is there. Click Select.

Don’t see your pet? Click the Refresh button at the top of the Custom pets section. Codex rescans ~/.codex/pets/.
Codex App settings showing the Custom pets section with an installed pet.

04

Wake it up

Pets are selected but not yet active. Wake yours into your workspace.

  • Type /pet in the Codex composer — canonical method.
  • Cmd+K → Wake Pet — keyboard shortcut path.

The pet appears in the top-right of your screen and follows you across windows.

Codex composer with /pet typed in.

This is what the loop produces.

Apex on the desktop, idle, while Codex asks what to build in hatchery.pet.
Apex on the desktop, idle, while Codex asks “What should we build in hatchery.pet?”

Your pet stays visible while you work. It reflects what Codex is doing — idle, thinking, working, or celebrating.

Troubleshooting.

Common stumbles, with the fix.

My pet isn’t in the Custom pets list.
Click Refresh at the top of the Custom pets section. If it still isn’t there, verify the install ran via ls ~/.codex/pets/, then reinstall: npx hatchery-pet install <slug>.
I installed but Codex doesn’t see anything.
Confirm the install command exited successfully. Check that ~/.codex/pets/<slug>/pet.json exists. Restart Codex App fully (quit and reopen).
My pet appeared but won’t wake.
Make sure the pet is Selected, not just listed. Try /pet in the composer. Try Cmd+K → Wake Pet.
I’m seeing weird visual artifacts.
Confirm you have the latest CLI: npm view hatchery-pet version should be 0.1.1 or higher. Reinstall the pet to get the current sprite.
How do I switch between pets?
Return to Settings → Appearance → Pets and click Select on a different pet.

What’s next.

Browse the catalog

Scan the launch roster of pets by sprite, state, rarity, and creator.

Open the catalog →

Read the API reference

The public REST API for the catalog, manifests, and install telemetry. Use it from your own clients or to inspect what the CLI writes.

Open /docs/api-reference →