petdex README

The project's README from github.com/crafter-station/petdex. As one markdown file: README.md.

Petdex

Petdex

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

petdex.dev  ·  Built with Petdex  ·  Discord  ·  npm

npm version GitHub stars MIT license GitHub issues

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.

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

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

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
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:

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.

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.

petdex (crafter-station/petdex)

Searching Database…

4.3K ·GitHub
Petdex
Что это?Petdex — это публичная галерея, CLI-установщик и десктоп-приложение, которые дарят агентам для кодинга вроде Codex, Claude Code, Gemini CLI и других анимированного питомца-маскота, реагирующего на активность агента в реальном времени.
Это одно приложение или несколько частей?Это три связанные части: веб-галерея на petdex.dev для просмотра и отправки питомцев, CLI, который устанавливает любого питомца одной командой, и десктоп-приложение, показывающее питомца поверх экрана и реагирующее на вашего агента.
Как запустить питомца?Выполните npx petdex install — файлы питомца лягут в ~/.petdex/pets/, затем скачайте десктоп-приложение с petdex.dev/download и подключите своего агента для кодинга в разделе Agents одним кликом.
С какими агентами для кодинга он работает?Petdex поддерживает Codex, Claude Code, DeepSeek Harness, Hermes, OpenCode, Gemini CLI и другие; нужен лишь npx, чтобы установить питомца, и один подключённый из этих агентов, чтобы ему было на кого реагировать.
Десктоп-приложение использует Electron или webview?Нет, десктоп-приложение — нативная сборка на SDK со встроенным Zig hook-сервером на 127.0.0.1:7777; в текущем релизном пути нет ни WebView, ни Node-sidecar.
Какие операционные системы поддерживает десктоп-приложение?Десктопный флоатер работает на macOS, Linux и Windows.
Какая лицензия у питомцев и у кода?Исходный код Petdex сам по себе под MIT, но спрайт-графика каждого питомца принадлежит отправившему её человеку под той лицензией, какую он объявит.
Как создать своего питомца?Используйте встроенный skill hatch-pet внутри Codex или соберите питомца в инструментах Petdex, затем отправьте его командой npx petdex submit ./my-pet/ или через веб-форму.
Что если питомец использует персонажа, права на который принадлежат мне?Petdex считает питомцев фан-артом от пользователей и не претендует на права на исходную интеллектуальную собственность; правообладатели могут подать запрос на удаление, и его рассмотрят в течение 48 часов.
Могу ли я построить свой клиент поверх Petdex?Да, HTTP API на petdex.dev/api/manifest возвращает slug, URL спрайтшита и состояния анимации каждого одобренного питомца, а открытые форматы pet.json и спрайтшитов задокументированы; на нём уже строят 21 проект.
Какие состояния анимации может показывать питомец?Нативный рендерер поддерживает девять состояний — idle, running-right, running-left, waving, jumping, failed, waiting, running и review — привязанных к хукам активности вашего агента для кодинга.
What are similar projects?react-starter-kit, noodle, golive-skill, crm, rankme.fast, onlook, git-city, chatbot
Which topics is it in?neon, pixel-art, desktop-pet, drizzle-orm, postgres, vercel, gemini-cli, bun, tailwindcss, oauth, dsh-plugin, redis
Creator
crafter-station
Size
76.2 MB
Stars
4.3K
Updated
CommitOct 10Releasedesktop-v0.9.2Sep 28
Age
5mo
Commits · 90 Days