Petdex

Petdex

The public gallery of animated companions for Codex.

Browse, install, and submit pets with one command.

petdex.dev · Built with Petdex · Discord · npm

What is Petdex

Petdex is three things working together:

• A web gallery at petdex.dev (opens in a new tab) where the community submits, reviews, and showcases animated pets in the Codex sprite format.
• A CLI that installs any pet on your machine with one command and ships them straight into Codex.
• A desktop app that floats a pet on your screen and reacts to your coding agent's activity in real time.

Every pet is a folder. Every folder is a Pokédex entry. Every entry is one npx petdex install away.

For users

Full CLI reference: [packages/petdex-cli/README.md](./packages/petdex-cli/README.md).

Personal collections are limited to 10 per account. The 24-pet limit bounds growth rather than the stored row, so a collection created before it existed can still be renamed or shrunk, but not grown. The CLI supports listing, creating, editing, deleting, and JSON output for automation.

For builders

If you want to build on top of Petdex (a desktop client, a wearable, an SDK, a Discord bot, anything), you have two stable surfaces:

• The HTTP API. petdex.dev/api/manifest returns every approved pet with its slug, spritesheet URL, animation states, and metadata.
• The pet package format. Every pet is a pet.json plus a spritesheet.{webp,png} rendered as an 8x9 grid of 192x208 frames, or the v2 8x11 grid.

21 open-source and source-available projects already build on these. See petdex.dev/built-with (opens in a new tab) for the catalog, then submit yours via the issue template (opens in a new tab).

Architecture

Web stack: Next.js 16, React 19, Tailwind, Drizzle, Postgres, Redis, Clerk, R2. CLI: Bun + TypeScript, ships as a single npm binary. Auth via Clerk OAuth + PKCE. Desktop: Native SDK app with an in-process Zig hook server on 127.0.0.1:7777. The current release path has no WebView or Node sidecar.

Pet package format

Every pet is two files:

The native renderer supports nine state rows: idle, running-right, running-left, waving, jumping, failed, waiting, running, and review. Codex and the supported coding agents map their activity hooks to these states. The v2 8x11 atlas leaves two additional rows available to the consuming client.

Pet IP and takedowns

Pets are user-submitted fan art. Petdex does not claim rights to any underlying IP. If you hold rights to a character and want a pet removed, file a takedown request (opens in a new tab) and we review within 48 hours.