The public gallery of animated pet for Codex, Claude Code, OpenCode y Gemini CLI
# Add to your Claude Code skills
git clone https://github.com/crafter-station/petdexGuides for using cli tools skills like petdex.
Last scanned: 6/7/2026
{
"issues": [
{
"type": "npm-audit",
"message": "@clerk/nextjs: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "@esbuild-kit/core-utils: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "@esbuild-kit/esm-loader: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "@jimp/core: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "@jimp/custom: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "@vibrant/image-node: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "drizzle-kit: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "esbuild: esbuild enables any website to send any requests to the development server and read the response",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "file-type: file-type affected by infinite loop in ASF parser on malformed input with zero-size sub-header",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "next: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "next-intl: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "node-vibrant: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "postcss: PostCSS has XSS via Unescaped </style> in its CSS Stringify Output",
"severity": "medium"
}
],
"status": "PASSED",
"scannedAt": "2026-06-07T07:56:15.624Z",
"npmAuditRan": true,
"pipAuditRan": true
}Petdex is three things working together:
Every pet is a folder. Every folder is a Pokédex entry. Every entry is one npx petdex install away.
Follow this checklist to get a pet installed, visible in Codex, and connected to the desktop app.
npx petdex install boba
You should see ~/.codex/pets/boba/ with pet.json and a spritesheet.
npx petdex init
This downloads the desktop app, starts it, and wires supported agents for /petdex.
Open Codex, go to Settings → Appearance → Pets, choose Boba, and click Select. Use /pet inside Codex to wake the pet or tuck it away.
Verify the setup:
npx petdex doctor
If hooks are installed, you can also type /petdex status inside a supported agent.
| 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.
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:
petdex.dev/api/manifest returns every approved pet with its slug, spritesheet URL, animation states, and metadata.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.
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.
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.
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.
npx petdex submit <path>.CONTRIBUTING.md, then open a PR.#wip, #ship-or-sink), feedback (#cli-feedback), and showcases (#showcase).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.
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.
No comments yet. Be the first to share your thoughts!
Top skills in this category by stars