crafter-station/petdex

Name: crafter-station/petdex
Author: crafter-station

插件Plugin ⭐ 3,978 MIT cat_label.claude-codecat_label.claude-code cat_label.clerkcat_label.clerk cat_label.clicat_label.cli cat_label.codexcat_label.codex 开发工具Developer Tools cat_label.drizzle-ormcat_label.drizzle-orm

A public gallery of animated pets for Codex, Claude Code, DeepSeek Harness, Hermes, OpenCode, Gemini CLI, and more.

项目介绍Project Overview

由知微Agent(zhiwei)编辑Edited by Zhiwei Agent (zhiwei)

Petdex 是 Codex 的动画宠物公共图库，整合 Web 画廊、CLI 与桌面应用。核心能力：通过 npx petdex install 一键安装宠物，桌面悬浮宠物会实时响应编码代理的工具调用。适用场景：为 Codex 工作流添加可交互的吉祥物。注意：桌面端为原生 SDK 应用，需分别下载安装，且部分功能依赖编码代理的 hook 集成。

Petdex is a public gallery of animated companions for Codex, combining a web showcase, an npm CLI, and a native desktop floater. Its core capability is one-command pet installation plus real-time animation driven by coding agent tool calls. Use it to add an interactive mascot to a Codex workspace. Caveat: the desktop app is a separate native SDK download for macOS, Linux, and Windows, and live reactions require compatible agent hook integration.

在 GitHub 查看View on GitHub

发给你的 DSH 安装Send to your DSH

请帮我了解并安装插件：【petdex】【https://github.com/crafter-station/petdex】

把上面这条消息直接发给当前会话里的 DSH，让它帮你了解并安装。安装命令不一定准确，发给 DSH 更稳。Send this message to DSH in your current session. CLI install commands may not be accurate across systems — DSH will figure it out for you.

或使用命令行安装（适合开发者）Or use CLI install (for developers)

命令行安装CLI Install

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

把 crafter-station/petdex 加入你的 DSH 配置（web profile）即可启用。

READMEREADME

7.5 KB · 缓存于 2026-08-23 03:40:39 · 7.5 KB

Petdex

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

petdex.dev · Built with Petdex · Discord · npm

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.

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:

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.

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

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.

Made by Crafter Station. Lead: @RaillyHugo.

渲染基于仓库 crafter-station/petdex 的 README.md。在 GitHub 查看原文 →

命令行安装CLI Install 复制安装命令Copy Install