Codex Pets
About

Codex Pets is the gallery for Codex companions

Browse community-made animated pet packs, install one with the npm CLI or MCP tools, or submit your own two-file pack for moderation.
npx @astandrik/codex-pets install zero-two-2
Browse gallerySubmit a petGitHubnpm packageAgent guide

Pack format

  • pet.json metadata
  • spritesheet.webp or spritesheet.png
  • 8x9 atlas at 1536x1872
  • reviewed before public listing

What Codex Pets is

Codex Pets is a public gallery for Codex-compatible animated pets. Each approved entry has a detail page, previewable animation states, a downloadable ZIP, and links to its source pet.json and spritesheet assets.

How a pet pack works

A pack is intentionally small: pet.json describes the pet metadata and animation settings, while spritesheet.webp or spritesheet.png contains the visual atlas. The current atlas is 8 columns by 9 rows at 1536x1872.

Install or submit

Approved pets can be installed from npm with the Codex Pets CLI. Creators can submit packs from the submit page; anyone can also request a generated pet. Admins review every submission before it appears in the gallery, sitemap, and public manifest.

YDB data layer

Codex Pets stores pet metadata, moderation state, counters, and binary assets in YDB. Local development can run against local-ydb; the related local-ydb-toolkit on GitHub captures the reusable local YDB workflow used around these projects.

Other projects that use local-ydb

The same reusable local YDB workflow also supports these sibling projects:

Agent access

Agents can connect to the public read-only Streamable HTTP MCP endpoint, or use the HTTP contract: the manifest, approved pet JSON, pet detail JSON at /api/pets/<slug>, share snippets, and the npm install command. Browser WebMCP is an optional enhancement for WebMCP-capable browsers that expose navigator.modelContext.
  • MCPcodex mcp add codexPets --url https://pets.ydb-qdrant.tech/mcp
  • Manifest/api/manifest
  • Share/api/pets/<slug>/share
  • Installnpx @astandrik/codex-pets install <slug>
  • Browser WebMCPsearch_codex_pets, get_codex_pet

FAQ

What is a Codex pet?

A Codex pet is a small animated companion that Codex can display while you work. Each public listing in this gallery is a downloadable pet pack with metadata and pixel art.

How do I install one?

Use the npm CLI command from the gallery or a pet detail page. The CLI reads the public manifest, downloads the pet files, and writes them into your Codex pets directory.

Can I submit my own pet?

Yes. Upload a ZIP, or upload pet.json plus spritesheet.webp or spritesheet.png from the submit page. If you need a new pet generated first, send a request instead.

What files does a pack need?

A pack needs pet.json and one spritesheet file at the root. The current validator expects an 8x9 atlas at 1536x1872, with each cell sized for Codex pet animation states.