Awesome Codex Pets

English | 简体中文

Ready-to-install pet packages for Codex Desktop, with a small npx CLI and scripts for catalog validation, preview GIF generation, and README gallery updates.

The npm package stays lightweight: it ships the CLI and catalog metadata, then downloads the selected pet assets from GitHub raw files during install. The source repository still keeps full pet packages under pets/ and generated preview GIFs under assets/previews/.

Usage

The CLI auto-detects your system language. You can override it with --lang en, --lang zh, or AWESOME_CODEX_PETS_LANG.

List available pets:

npx awesome-codex-pets list

Install a pet into Codex:

npx awesome-codex-pets install <pet-id>

The install command downloads only the selected pet assets, prints the resolved install path, and shows the manual activation path: Codex Desktop -> File -> Settings -> Appearance -> Pet. Choose the pet there, then wake Codex Desktop.

Optionally try best-effort automatic activation:

npx awesome-codex-pets apply <pet-id>

apply ensures the package is installed, writes the active marker, and tries to update known Codex persisted selection keys such as selected-avatar-id when they exist and are writable. Some Codex Desktop builds do not react to that state write immediately, so the UI path above remains the reliable fallback.

Diagnose common activation problems:

npx awesome-codex-pets doctor

Start a pet contribution draft:

npx awesome-codex-pets add-pet init <pet-name> --author <author-or-profile>

Import a finished pet package or hatch-pet output:

npx awesome-codex-pets add-pet import --draft <pet-id>

Finalize generated catalog, previews, README gallery, and validation:

npx awesome-codex-pets add-pet finalize <pet-id>

Direct install from GitHub raw files:

curl -fsSL https://raw.githubusercontent.com/huaqingai/awesome-codex-pets/main/scripts/install-pet.sh | bash -s -- <pet-id>

Codex loads custom pets from ${CODEX_HOME:-$HOME/.codex}/pets/<pet-id>. After installation, open Codex Desktop -> File -> Settings -> Appearance -> Pet and choose the installed pet, then wake Codex Desktop. If the pet still does not appear after selection, restart Codex Desktop. apply is optional and best-effort; if it does not switch the visible pet, use the same UI path.

Pet Catalog

Mascots

Anime Characters

Animals

Original Characters

Maintainer Workflow

Add a pet package under pets/<pet-id>/:

pets/<pet-id>/
  submission.json
  pet.json
  spritesheet.webp

For new contributions, prefer the guided local workflow. init writes a draft under .codex-pets/drafts/ so an incomplete pet does not break validation. import creates the real pets/<pet-id>/ package only after pet.json and spritesheet.webp are available. finalize syncs generated files:

npm install
npx awesome-codex-pets add-pet init <pet-name> --author <author-or-profile>
npx awesome-codex-pets add-pet import --draft <pet-id>
npx awesome-codex-pets add-pet finalize <pet-id>

Manual maintenance still works with npm run catalog:sync, npm run previews, npm run readme, and npm run validate.

Release Workflow

Publishing is handled by GitHub Actions when a version tag is pushed. Configure the repository secret NPM_TOKEN with an npm automation token that can publish awesome-codex-pets.

For the first release, commit the current 0.1.0 changes and push the matching tag:

git push origin main
git tag v0.1.0
git push origin v0.1.0

For later releases, bump the version first:

npm version patch
git push origin main --follow-tags

The release workflow requires the tag to match package.json exactly, for example v0.1.0. It runs npm ci, npm run build, checks that generated files are committed, publishes to npm with provenance, and creates a GitHub Release. Pet spritesheets and preview GIFs are intentionally not bundled in npm; the CLI uses catalog.rawBaseUrl to download selected pet assets from GitHub on demand.

The preview generator reads the Codex atlas contract: 1536x1872, 8x9 grid, 192x208 cells, transparent background. It writes one GIF per state to assets/previews/<pet-id>/<state>.gif.

See docs/PET_FORMAT.md and docs/ADDING_PETS.md for the package and contribution details. See ROADMAP.md for planned install, activation, and pet-development workflow improvements.