Awesome Codex Pet

简体中文 | English

🌐 Live gallery · ⚡ Install guide · 📖 Submit a pet

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

Highlights

• 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.

Pet Versions

Version	Atlas	Runtime metadata	Use
v1	1536x1872, 8 columns × 9 rows	omit spriteVersionNumber or set it to 1	Existing standard-animation pets
v2	1536x2288, 8 columns × 11 rows	set spriteVersionNumber: 2	Standard animations plus 16 clockwise look directions

Both versions remain installable. Use v1 when maintaining an existing 9-row pet; use v2 for newly upgraded pets that need directional looking.

Quick Install

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.

Upgrade an Existing v1 Pet

1. Open Codex Settings → Pets.
2. Find the installed custom pet and choose Update.
3. Codex opens a Hatch Pet task. The current v2 workflow validates and preserves the existing 9 animation rows, generates four cardinal anchors plus 16 look directions, then writes an 11-row atlas with spriteVersionNumber: 2.
4. Review the generated contact sheet and direction previews before accepting the replacement.

The Update action is an AI-assisted v1-to-v2 conversion, not a download notification from this repository. It updates the local package under ~/.codex/pets/; it does not modify or submit the GitHub copy automatically.

Pets

Anime Characters

Name	Firefly · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- firefly--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Acheron · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- acheron--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Arlecchino · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- arlecchino--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Black Swan · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- black-swan--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Castorice · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- castorice--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Cyrene · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- cyrene--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Doro · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- doro--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Frieren · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- frieren--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Furina · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- furina--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Hu Tao · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- hu-tao--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Kamisato Ayaka · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- kamisato-ayaka--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Mahiro · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- mahiro--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Mihari · by @Hyoni1129 · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- mihari--hyoni1129
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Mikoto · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- mikoto--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Miku · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- miku--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Nahida · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- nahida--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Navia · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- navia--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Paimon · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- paimon--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Raiden Shogun · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- raiden-shogun--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Reimu · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- reimu--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Robin · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- robin--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Ruan Mei · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- ruan-mei--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Silver Wolf · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- silver-wolf--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Sparkle · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- sparkle--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Tingyun · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- tingyun--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	女弹药Q · by @QunBoo · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- dnf-female-ammo--qunboo
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Bocchi · by @legeling · Anime Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- bocchi--lingxiaotian
Action	Idle	Waving	Running	Waiting	Review
Preview

Original Characters

Name	Aemeath Mini · by @cuNuo · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- aemeath-mini--cunuo
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Apu · by @xchangee · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- apu--xchangee
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Claude · by @xiangking · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- claude--xiangking
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Diaoyi Baobao · by @D1a0y1bb · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- diaoyi-baobao--d1a0y1bb
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Hajimi · by @zeyuwang1999 · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- hajimi--zeyuwang1999
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Hana2 · by @initiatione · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- hana2--initiatione
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Lulu · by @YoGazz · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- lulu--yogazz
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Mika · by @ROTl24 · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- mika--rotl24
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Night Neko · by @netizenXuan · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- night-neko--netizenxuan
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	RuRuKa · by @ltmcliao-cmyk · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- ruruka--ltmcliao-cmyk
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Saki · by @rookie-09 · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- saki--rookie-09
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Shian · by @mistyShen · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- shian-helper--mistyshen
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Wally · by @wally025 · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- wally--wally025
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Xian Xiao Lu · by @qingyunAGI · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- xian-xiao-lu--qingyunagi
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Yi Er · by @gbn666 · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- yier--gbn666
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Yuanzai · by @Gaming33 · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- yuanzai--gaming33
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Yuzubou · by @Keseras34938976 · Original Characters · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- yuzubou--keseras34938976
Action	Idle	Waving	Running	Waiting	Review
Preview

Memes

Name	Katana Cheems · by @Thankyou-Cheems · Memes · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- katana-cheems--thankyou-cheems
Action	Idle	Waving	Running	Waiting	Review
Preview

Animals

Name	Becky · by @NateWanggg · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- becky--natewanggg
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Bubu · by @gbn666 · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- bubu--gbn666
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Corgi Companion · by @cxian0928-afk · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- corgi-companion--cxian0928-afk
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Diandian · by @LLLucasXU · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- diandian--lllucasxu
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Fleta · by @NateWanggg · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- fleta--natewanggg
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Frankie · by @AygunVarol · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- frankie--aygunvarol
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Little Sheep · by @MingDong · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- little-sheep--mingdong
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Mai · by @DwDestiny · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- mai--dwdestiny
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Mimi · by @Spacebody · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- mimi--spacebody
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Panda · by @Jason-Bai · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- panda--jason-bai
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Teddy · by @danieloleary · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- teddy--danieloleary
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	Tian Hua Hua · by @D1a0y1bb · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- tian-hua-hua--d1a0y1bb
Action	Idle	Waving	Running	Waiting	Review
Preview

Name	自嘲熊 · by @z-kzhang · Animals · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- zichao-xiong--z-kzhang
Action	Idle	Waving	Running	Waiting	Review
Preview

Robots

Name	CodeNoNo · by @Dqd02 · Robots · v1
Install	curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- codenono--dq02
Action	Idle	Waving	Running	Waiting	Review
Preview

Submit a Pet

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. A v1 submission may omit spriteVersionNumber and must provide a 1536x1872 WebP. A v2 submission must set spriteVersionNumber: 2 and provide a 1536x2288 WebP.

The v2 runtime manifest looks like:

{
  "id": "pet-slug--author-slug",
  "displayName": "Pet Name",
  "description": "One short sentence.",
  "spriteVersionNumber": 2,
  "spritesheetPath": "spritesheet.webp"
}

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. Do not submit prompts, references, QA folders, contact sheets, videos, decoded frames, or Hatch Pet run directories. Maintainers or CI regenerate previews, README listings, and pets.json after merge, but preview binaries are not kept as tracked Git assets.

Make a Pet

• .agents/skills/hatch-pet-v1 — preserve or repair a legacy 8x9 v1 pet
• .agents/skills/hatch-pet-v2 — create or upgrade an 8x11 v2 pet with 16 look directions

Choose the skill explicitly. For an upgrade, give $hatch-pet-v2 the existing installed pet.json and spritesheet.webp; approved rows 0–8 are retained rather than regenerated.

Documentation

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

License

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