What is Petdex
Petdex is three things working together:
- A web gallery at petdex.dev 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.
Quick start
Follow this checklist to get a pet installed, visible in Codex, and connected to the desktop app.
- Install a known pet:
npx petdex install boba
You should see ~/.petdex/pets/boba/ with pet.json and a spritesheet.
-
Get the desktop app from petdex.dev/download. It
runs on macOS, Linux and Windows.
-
Open it, then hit Cmd+, over the pet to open Settings.
Pick your pet under Pets, and connect your coding agents under Agents
with one click each. No terminal involved.
The pet floats above your workspace and animates on every tool call your agent
makes.
Signed-in creators can also group approved pets into personal collections from
the profile's Collections tab or the CLI:
npx petdex collection create --title "My pets" --pets boba,mochi
For users
| You want to... | Do this |
|---|
| Browse pets | Visit petdex.dev |
| Install a pet | npx petdex install <slug> |
| Switch active mascot | Open Settings in the desktop app (Cmd+,) |
| Run the desktop floater | Download it from petdex.dev/download |
| 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 |
| Manage collections | npx petdex collection list or use the Collections tab on your profile |
| Join the community | Discord |
Full CLI reference: 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 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), collection management, 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` catalog client (auth, list, install, submit, edit, collection management)
│ ├── petdex-desktop-native/ Native SDK floating mascot for macOS, Linux and Windows
│ ├── petdex-desktop-windows/ Legacy Tauri Windows implementation (not the release path)
│ └── 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: 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.
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 8x9 or v2 8x11 frame grid of 192x208 px each (or .png)
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.
Contribute
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.
