---

What is Petdex

Petdex is three things working together:

1. A web gallery at petdex.dev where the community submits, reviews, and showcases animated pets in the Codex sprite format.
2. A CLI that installs any pet on your machine with one command and ships them straight into Codex.
3. 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.

Quick start

Follow this checklist to get a pet installed, visible in Codex, and connected to the desktop app.

1. Install a known pet:

npx petdex install boba

You should see ~/.codex/pets/boba/ with pet.json and a spritesheet.

1. Initialize Petdex Desktop and agent hooks:

npx petdex init

This downloads the desktop app, starts it, and wires supported agents for /petdex.

1. Open Codex, go to Settings → Appearance → Pets, choose Boba, and click Select. Use /pet inside Codex to wake the pet or tuck it away.

2. Verify the setup:

npx petdex doctor

If hooks are installed, you can also type /petdex status inside a supported agent.

For users

You want to...	Do this
Browse pets	Visit petdex.dev
Install a pet	npx petdex install <slug>
Switch active mascot	npx petdex select (interactive picker) or npx petdex select <slug>
Run the desktop floater	npx petdex init (downloads the .dmg and wires Codex/Claude Code hooks)
Make a pet	Use the hatch-pet skill inside Codex, or build one with the Petdex creator tools
Submit a pet	npx petdex submit ./my-pet/ or drop it through the web submitter
Join the community	Discord

Full CLI reference: packages/petdex-cli/README.md.

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 8×9 grid of 192×208 frames.

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

Architecture

crafter-station/petdex
├── src/
│   ├── app/[locale]/          Public site: gallery, /pets/<slug>, /collections, /built-with, /community, /create, /download, /submit, /u/<handle>, ...
│   ├── app/api/cli/           CLI endpoints: OAuth config, submit (zip → presigned R2), dedup check, register
│   ├── app/api/manifest/      Public manifest: every approved pet with its spritesheet URL
│   ├── app/api/admin/         Admin review surface for submissions, edits, collection requests
│   └── lib/db/schema.ts       Drizzle schema (Postgres)
├── packages/
│   ├── petdex-cli/            npm `petdex` (auth, list, install, select, submit, hooks, init)
│   ├── petdex-desktop/        Zig + WebKit floating mascot for macOS
│   └── discord-bot/           Discord.js bot for the Petdex server
├── public/built-with/         Screenshots for the community page
├── public/brand/              Logos, OS icons, Discord icon
└── drizzle/                   SQL migrations (Postgres schema history)

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: Zig on a fork of vercel-labs/zero-native, HTTP sidecar in Node for agent hooks.

Develop locally

Two paths are supported.

Goal	Command	Setup
Local full stack	bun run dev:docker	Docker or Podman, ~30s warm-up.
Run against real services	bun run dev	.env.local filled (maintainers only).

git clone https://github.com/crafter-station/petdex.git
cd petdex
bun install
bun run dev:docker

Open localhost:3000. Full guide in CONTRIBUTING.md.

Pet package format

Every pet is two files:

my-pet/
├── pet.json                Metadata: name, slug, tags, vibes, kind, frame size, animation states
└── spritesheet.webp        9 rows × 8 cols = 72 frames of 192×208 px each (or .png)

Animation states are the rows: idle, wave, run, failed, review, jump, extra1, extra2. Codex maps these to its agent activity hooks. Loop timing defaults to 1100ms at 6 frames per state.

Contribute

• Submit a pet: petdex.dev/submit or npx petdex submit <path>.
• List your project: open a Built with Petdex issue.
• Fix a bug or add a feature: read CONTRIBUTING.md, then open a PR.
• Hang out: Discord has channels for shipping (#wip, #ship-or-sink), feedback (#cli-feedback), and showcases (#showcase).

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 and we review within 48 hours.

License

The source code is MIT. Pet assets are owned by their submitters under whatever license they choose to declare.

---