Awesome Codex Pet

September 23, 2026 · View on GitHub

Awesome Codex Pet

简体中文 | 한국어 | 日本語 | Español | English

Browse and install free community Codex pets at codexpet.top →

Awesome Codex Pet is a free community pet gallery. Browse complete animations like a pet store, install a favorite without cloning the repository, or request a missing character that a community contributor may volunteer to make.

Browse pets · Install a pet · Request a character

Open the Awesome Codex Pet gallery

pets: 255 categories: 11 languages: en | zh--CN | ko | ja | es code: MIT assets: CC BY--NC 4.0 install: one command Pet previews

This repository is the source catalog behind codexpet.top: it keeps installable pet packages, creator attribution, collection metadata, validation tools, and contribution history. For browsing and installing pets, start with the website.

Highlights

  • One-command install — no clone, no manual setup, works on macOS / Linux / Windows
  • Free community gallery — complete animation previews, collections, creator profiles, weekly rankings based on installs and likes, sharing, and community statistics at codexpet.top
  • Free character requests — submit a character and references without making a spritesheet; a community contributor may volunteer to create it, with no delivery guarantee
  • AI-first contributions — contributors can create, repair, and submit pets with Codex; advanced contributors can still open a PR
  • 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.

Repository-defined series and collections live in collections.json. Use kind: franchise for pets from the same original work and kind: theme for cross-franchise groups connected by a shared subject or style. A pet joins either by listing its slug in submission.json.collections; the catalog and website are generated from that metadata. Membership is recorded immediately, while the website publishes a collection only after it has at least three pets.

submission.json.name is the required fallback name. Creators may keep a pet single-language by omitting localized_names, or opt into bilingual naming by providing both localized_names.en and localized_names.zh. The website follows the visitor's selected language and never invents a translation.

Pet Versions

VersionAtlasRuntime metadataUse
v1`1536x1872$, 8 \text{columns} \times 9 \text{rows}\text{omit} $spriteVersionNumberor set it to1`Existing standard-animation pets
v2`1536x2288$, 8 \text{columns} \times 11 \text{rows}\text{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

Install Node.js 20+ first. No clone required. The same npm command works on every platform:

# Node.js 20+ · macOS / Linux / Windows
npx --yes @legeling/codex-pet install firefly--lingxiaotian

CLI: list / search / download / contribute

npx @legeling/codex-pet

# From a local clone with Node.js
npm run install:pet -- firefly--lingxiaotian

List available pets:

npx --yes @legeling/codex-pet 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. Installers verify the repository manifest and SHA-256 hashes, stage files before activation, and require --force when replacing an existing package. Pin the npm package version and pass --raw-base with an immutable repository commit for reproducible installs.

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

Browse all pets and animations →

Firefly
Firefly		Kid Goku
Kid Goku		Rem
Rem		大笑奶龙
大笑奶龙		Shin-chan
Shin-chan
Frieren
Frieren		Buba
Buba		Paimon
Paimon		乌萨奇
乌萨奇		Conan Edogawa
Conan Edogawa
Furina
Furina		Doraemon
Doraemon		Jiji
Jiji		Citlali
Citlali		Miku
Miku
Full pet index (text only) · 255

Game Characters

Anime Characters

Original Characters

Mascots

Animals

Fantasy Creatures

Robots

Human Avatars

Memes

Objects & Props

Others

Request or Submit a Pet

Missing a favorite character? Open the free community request page. Submitting is free, no spritesheet is required, and a community contributor may volunteer to make the pet. Requests are not acceptance or delivery promises.

Contributors can start with the website contribution guide. It offers three paths without making every contributor download this large asset repository:

  1. Request a pet — Codex checks for duplicates, gathers references and requirements, then opens a labeled request issue.
  2. Create or submit your own pet — Codex can start from references or existing files, complete and validate the three-file package, then use the GitHub API to create a focused branch and pull request without a full clone.
  3. Advanced pull request — experienced contributors can work in a GitHub Codespace, a partial clone, or their preferred Git workflow.

The repository skill at .agents/skills/submit-codex-pet teaches compatible AI agents how to choose the right route. When credentials or repository write access are unavailable, it falls back to a labeled submission issue instead of losing the contributor's work.

Advanced contributors should add exactly one final package:

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

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

Star History

GitHub star history for Awesome Codex Pet

The chart is refreshed daily from GitHub's stargazer data. Star the repository to help more people discover these pets.

Contributors

Awesome Codex Pet contributors

Thanks to everyone who contributes pets, code, documentation, reviews, and ideas.

License

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