A curated gallery of community-made Codex pets. Browse animations on the website, install with one command, and submit your own pet through GitHub.

• One-command install — no clone, no manual setup, works on macOS / Linux / Windows
• Live gallery — animated previews, filtering, and view/install counters at awesome-codex-pet.pages.dev
• GitHub-native submissions — open an issue or PR, the rest is automated
• Open licensing — code under MIT, pet assets under CC BY-NC 4.0

Each pet is a small shareable package:

pets/<pet-slug>--<author-slug>/
├── submission.json
├── pet.json
└── spritesheet.webp

Preview images are generated into assets/previews/<pet-id>/ as local or CI build output, never inside the pet folder.

No clone required. Pick the script for your shell:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- firefly--lingxiaotian

# Windows PowerShell
powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -UseB https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.ps1 | iex; Install-CodexPet firefly--lingxiaotian"

# Anywhere with Node.js
npx awesome-codex-pet firefly--lingxiaotian

List available pets:

curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- --list

Default install locations:

• macOS / Linux: ~/.codex/pets/<pet-id>/
• Windows: %USERPROFILE%\.codex\pets\<pet-id>\

Set CODEX_HOME to override, or AWESOME_CODEX_PET_NO_STATS=1 to opt out of anonymous install counters.

The fastest path is the submission guide on the website. It walks through categories, the folder layout, and the reviewer checklist.

If you prefer working from the repo:

pets/
└── pet-slug--author-slug/
 ├── submission.json
 ├── pet.json
 └── spritesheet.webp

Use pet-slug--author-slug so multiple authors can ship variants of the same character. Generated previews and README listings are produced by CI:

python -m pip install -r requirements.txt
npm run validate:pr
npm run lint

Contributor PRs should only include submission.json, pet.json, and spritesheet.webp. Maintainers or CI regenerate previews, README listings, and pets.json after merge, but preview binaries are not kept as tracked Git assets.

• .agents/skills/hatch-pet — end-to-end pipeline for designing, generating, QAing, and packaging a pet

• English: docs/en
• 简体中文: docs/zh-CN
• Web gallery source: web/
• Stats worker: worker/
• Contribution guide: CONTRIBUTING.md

• Code and scripts: MIT
• Pet assets and generated previews: CC BY-NC 4.0, unless a pet folder says otherwise