Petdex

The public gallery of animated companions for Codex.
Browse, install, and submit pets with one command.

petdex.crafter.run  ·  Built with Petdex  ·  Discord  ·  npm

---

What is Petdex

Petdex is three things working together:

1. A web gallery at petdex.crafter.run 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

# Pick a pet. Install it. Your Codex desktop app picks it up automatically.
npx petdex install boba

# Or run the full Petdex desktop app with bubble UI and agent hooks.
npx petdex init

Open Codex, go to Settings → Appearance → Pets, and pick the one you just installed.

For users

You want to...	Do this
Browse pets	Visit petdex.crafter.run
Install a pet	npx petdex install <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.crafter.run/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.

13 open-source projects already build on these. See petdex.crafter.run/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, 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

Three paths, pick the one that matches what you want to change.

Goal	Command	Setup
UI, copy, i18n, CSS	bun run dev:mock	Zero credentials. In-process Postgres + stubbed Clerk.
DB queries, auth, submit, likes	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:mock

Open localhost:3000. You're auto-signed-in as contributor@petdex.local. 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        8 rows × 9 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.crafter.run/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.

---

Made by Crafter Station. Lead: @RaillyHugo.