One-line Description

Petdex is a public gallery and CLI tool for animated pet companions in Codex (ChatGPT desktop app), turning "a little animal running on screen while you code" into a browsable, installable, and community-contributable content ecosystem. Beyond the DSH installation entry, it's a standalone Next.js web app with an npm CLI, desktop floating window app, and Discord community bot.

Core Features

• Browse approved pets in a public gallery, filterable by vibe, kind (creature/object/character), and sp version
• Install pets locally with a single CLI command to ~/.petdex/pets/<slug>/ and ~/.codex/pets/<slug>/
• Submit new pets: upload folder or zip, automatically run dHash deduplication, AI review, color scheme/tag/sound generation
• Public HTTP manifest (v1 + v2) for third-party desktop clients, wearables, and SDKs to fetch pet lists
• Desktop floating window SDK draws a pixel pet on screen, switching between 9 animation states like idle/running/failed based on coding agent activity hooks
• Discord community bot: slash commands, auto roles, auto-post to #showcase channel when pets are approved

Technical Implementation

• Languages: TypeScript (Web main site + CLI + desktop native SDK bridge) + Zig (desktop SDK in-process hook server, listening on 127.0.0.1:7777)
• Key Dependencies: Next.js 16.3.0, React 19.2.8, Drizzle ORM + Postgres (Neon), Clerk OAuth, R2 (assets) / Aliyun OSS (fallback), Upstash Redis (rate limiting/caching), Vercel AI SDK (auto review/tagging/ffmpeg sound generation), Resend (email), discord.js v14, @napi-rs/keyring (optional keychain for CLI)
• Architecture: Single repo multi-package: root is Next.js main site; packages/petdex-cli is Bun-bundled single-file Node CLI; packages/discord-bot is discord.js; packages/petdex-desktop-native is Zig + cross-platform floating window; main site serves Web/CLI/submit scenarios via /api/manifest, /api/cli/*, /api/submit route groups
• Entry Files: Main site src/app/[locale]/page.tsx (homepage) / src/app/api/manifest/route.ts (public manifest entry); CLI entry packages/petdex-cli/bin/petdex.ts; Discord bot packages/discord-bot/src/bot.ts

Use Cases

Active users of Codex desktop app or Claude Code and other coding agents who want a small pet companion while working and don't want to deal with complex configuration—a single command to install, and the desktop app automatically translates agent activity into pet animations. Also creators who want to share their pixel art pets with the entire community; submissions go through AI + human review dual-track process.

Prerequisites & Compatibility

Installation

dsh plugin --profile web add github:crafter-station/petdex

Configuration

This plugin requires no extra configuration. dsh plugin add installs pet content (to ~/.petdex/pets/ and ~/.codex/pets/), not the petdex.dev site itself; all environment variables needed for site deployment (DATABASE_URL, R2_*, CLERK_*, UPSTASH_*, RESEND_API_KEY, OPENAI_API_KEY, AI_GATEWAY_API_KEY, PETDEX_ADMIN_USER_IDS, PETDEX_ALL_PETS_PACK_URL, PETDEX_MANIFEST_V1_URL, PETDEX_MANIFEST_V2_URL, etc.) only matter for those who want to run petdex.dev themselves—nothing to worry about for plugin installation.

FAQ

Q: Is petdex a DSH plugin or an independent project?

A: This repo is the source code for the entire petdex.dev ecosystem (Next.js main site + npm CLI + Discord bot + desktop native SDK), not like a normal DSH plugin that injects into the host via dsh.bundle.patch. dsh plugin add here is more like a convenient entry point that installs pets locally to ~/.petdex/pets/ and ~/.codex/pets/.

Q: What's the file structure of a pet?

A: Each pet is a folder with pet.json at root (describing name/animation state/frame dimensions) + spritesheet.webp or .png, requiring 8×9 frame grid (1536×1872) or v2's 8×11 grid (1536×2288). v1/v2 is distinguished by the spriteVersionNumber field; old 8×9 is for backward compatibility.

Q: How to install a pet to the Codex desktop app?

A: Browse/copy the slug on petdex.dev, then run npx -y petdex install <slug>; or use Petdex desktop app (download from petdex.dev/download) settings panel to one-click connect to Claude Code/Codex and switch the currently active pet.

Q: What do the CLI and desktop app each manage?

A: CLI (npm name petdex) only handles directory browsing, installation, submission, and editing published metadata; hook injection, updates, agent connection, and switching the currently active pet are all handled by the desktop app's settings panel. Starting from v1.0.0, CLI removed init/hooks/select/desktop subcommands—all now handled by the desktop app.

Q: Any limits on pet submissions?

A: 10 submissions per user per day; slug name collisions auto-add suffix (boba → boba-2); submissions require petdex login first (browser OAuth PKCE); CI/headless environments must complete login locally beforehand. No email notifications without owner email; submission identity comes from Clerk session or CLI bearer token.

Q: What can third parties do with the public API?

A: petdex.dev/api/manifest (v1, R2 redirect) and /api/manifest/v2 (v2) return all approved pets' slugs, spritesheet URLs and metadata, cached for 300 seconds; /api/manifest/full provides the full dataset. Any desktop client, wearable, or SDK can build upon these two manifests + pet package format.

Q: How to uninstall a pet?

A: Simply delete both ~/.petdex/pets/<slug>/ and ~/.codex/pets/<slug>/ directories; CLI has no dedicated uninstall command. Approved pets won't be removed from the pet gallery website.

Learning Curve

Beginner — a single npx -y petdex install <slug> brings a pet to Codex with no config files or environment variables to fill in; you only move to the next level when you want to contribute submissions or set up a local instance.

Known Issues & Limitations

• bun run dev:mock is deprecated; executing it exits immediately; it's only for mock unit tests to reuse .env.mock, not for starting the site
• Codex desktop app's codex://pets/install link parser has zero tolerance for unknown query parameters, and the modal consuming that link is still gated off by Statsig, so even correctly formed links won't trigger; must read docs/chatgpt-pet-integration.md before making changes
• Many scripts/apply-* / scripts/backfill-* scripts in root are one-time maintenance scripts for real databases (run manually), not regular bun run commands
• bun run dev (maintainer) requires full credentials for Clerk, Neon or local Postgres, R2, Upstash, Resend, OpenAI, ElevenLabs; regular contributors should use bun run dev:docker
• Pets are user-submitted fan art; Petdex itself doesn't claim IP; rights holders can request takedowns via GitHub issue using the takedown template

---

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 ~/.petdex/pets/boba/ with pet.json and a spritesheet.

2. Get the desktop app from petdex.dev/download. It runs on macOS, Linux and Windows.

3. 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.

For users

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 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), 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)
│   ├── 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.

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

• 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.

---