# Codex pets

The pet companion in the web app can adopt pets packaged by the upstream
Codex `hatch-pet` skill. This doc explains where those pets live, how
Open Design discovers them, and what to do if you do not have Codex
installed.

## Where pets live

The daemon scans this directory on every list request:

```
${CODEX_HOME:-$HOME/.codex}/pets/<pet-id>/
  pet.json          # { id, displayName, description, spritesheetPath }
  spritesheet.webp  # 1536x1872 8x9 atlas (.png / .gif also accepted)
```

`CODEX_HOME` is honoured if set; otherwise the daemon falls back to
`~/.codex/pets/`. Both paths follow the upstream Codex conventions.

The scan is implemented in `apps/daemon/src/codex-pets.ts` and surfaced
through `GET /api/codex-pets` (list) and
`GET /api/codex-pets/:id/spritesheet` (raw bytes). The web pet settings
panel calls these endpoints from
`apps/web/src/components/pet/PetSettings.tsx` under the
"Recently hatched" section.

## I do not have Codex installed

You do not need Codex to use Open Design. The pet companion ships with
built-in pets that work out of the box. The "Recently hatched" section
will simply stay empty until something appears under
`${CODEX_HOME:-$HOME/.codex}/pets/`.

You have three ways to populate it without running Codex:

1. **Sync the public catalogs.** Run
   `node --experimental-strip-types scripts/sync-community-pets.ts`
   (see the script header for flags). It downloads pets from the
   community catalogs into the canonical Codex layout, then they show
   up under "Recently hatched" on the next refresh.
2. **Drop a pet folder in by hand.** Create
   `~/.codex/pets/<your-pet>/` with a `pet.json` and a
   `spritesheet.webp` (8x9 atlas). The daemon does not require Codex to
   be installed — it only needs the directory.
3. **Run the vendored skill in any chat agent.** The `hatch-pet` skill
   is vendored under `skills/hatch-pet/`. Any agent that can execute
   skills (Codex, or any other) can run it end-to-end and write into the
   same directory.

If `~/.codex/pets/` does not exist, the daemon does **not** auto-create
it — empty list is returned and the UI shows "no recently hatched pets
yet". Creating the directory is intentionally an explicit user step so
the daemon does not write into external tool homes without a user opting in.
Before documenting daemon-owned write paths, you MUST read root `AGENTS.md` →
**Daemon data directory contract**; this guide MUST NOT restate it.

## Manifest shape

The `pet.json` manifest is read defensively — every field is treated as
optional and validated as a string before use. The shape we honour:

```json
{
  "id": "shiba-pomegranate",
  "displayName": "Shiba Pom",
  "description": "Friendly pixel-art shiba.",
  "spritesheetPath": "spritesheet.webp"
}
```

Notes:

- The folder name is the on-disk identity. The list endpoint reports
  the sanitised folder name as the public `id` so that
  `/api/codex-pets/:id/spritesheet` can resolve it directly even when
  `manifest.id` differs from the folder name (e.g. the manifest declares
  spaces or punctuation that get sanitised away).
- `spritesheetPath` is resolved relative to the pet folder and is
  rejected if it would escape the folder. If unset, we fall back to
  `spritesheet.webp`, then `.png`, then `.gif`.
- Any field that is not a non-empty string is ignored and the UI falls
  back to a sensible default (folder name → display name, empty
  description, etc.).

## Related code

- Daemon registry + manifest validation: `apps/daemon/src/codex-pets.ts`
- HTTP routes (list + spritesheet): `apps/daemon/src/server.ts`
- Web list / adopt UI: `apps/web/src/components/pet/PetSettings.tsx`
- Shared response types: `packages/contracts/src/api/registry.ts`
- Vendored skill source: `skills/hatch-pet/`
- Community catalog sync script: `scripts/sync-community-pets.ts`