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 构建，内置一个运行在 127.0.0.1:7777 上的进程内 Zig 钩子服务器；当前的发布路径中不含 WebView 或 Node sidecar。
桌面应用支持哪些操作系统？桌面悬浮窗可运行在 macOS、Linux 和 Windows 上。
宠物与代码分别采用什么授权？Petdex 源代码本身采用 MIT 协议，但每只宠物的精灵图素材归其提交者所有，并以其自行选择声明的任何协议授权。
如何创建我自己的宠物？可以使用 Codex 内置的 hatch-pet 技能，或者用 Petdex 的创作者工具制作一只，然后通过 npx petdex submit ./my-pet/ 或网页提交入口进行提交。
如果某只宠物使用了我拥有权利的角色会怎样？Petdex 将宠物视为用户提交的同人作品，不主张对底层 IP 拥有任何权利；权利人可以提交下架请求，请求会在 48 小时内得到审核。
我可以在 Petdex 之上构建自己的客户端吗？可以。petdex.dev/api/manifest 的 HTTP API 会返回每只已获批准宠物的 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, acryl
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