文档

按这份清单走完，就能把宠物装好、在你的智能体里看到它，并接上桌面应用。安装不需要账号，只有提交作品时才需要登录。

1. 1

   先安装一只已知宠物

   先从 Boba 开始，这样你就有一个真实的宠物文件夹可以选择。

   你应该能看到 ~/.codex/pets/boba/，里面包含 pet.json 和 spritesheet。

   $ npx petdex install boba
2. 2

   初始化桌面应用和 hooks

   下载桌面应用。它会在设置窗口里连接你的编程智能体，无需终端。

   宠物漂浮在工作区上方，对每次工具调用做出反应。

   下载 Petdex Desktop
3. 3

   在应用中选择宠物

   打开 ChatGPT 桌面应用，前往 Settings → Appearance → Pets，选择 Boba，然后点击 Select。

   在应用内使用 /pet 唤醒宠物或把它收起来。

4. 4

   验证配置是否正常

   如果宠物没有出现，运行诊断命令；安装 hooks 后，也可以在支持的 agent 里输入 /petdex status。

   doctor 会指出缺失的 binary、hook、token 或宠物目录，并给出具体修复提示。

CLI 支持 Node 20+（也支持 Bun）。按你的使用习惯选一种方式即可，两种方式的能力和会话持久化都一样。

快速安装

直接用 npx。无需提前配置，第一次运行后包会被缓存。

全局安装

全局安装后可以立即调用，也更适合长期高频使用。

两种方式的登录持久化完全一样。Token 会保存在系统钥匙串里（macOS Keychain、Windows Credential Manager、Linux Secret Service），服务名是 petdex-cli。即使 npx 清掉了包缓存，你的登录状态也还在。

登录一次之后，submit 这类需要身份的命令就能直接运行。

登录流程使用 OAuth 2.0 + PKCE：CLI 会打开浏览器，你在 accounts.petdex.dev 通过 Clerk 登录，浏览器再把授权码回传给一次性的 localhost listener。CLI 会用授权码换取 token，并保存到系统钥匙串。密钥不会明文落盘。

其它登录相关命令：

CLI 覆盖完整流程：发现、安装、孵化、发布，以及桌面应用和 Agent hooks。所有命令都支持 --help。

petdex list

列出所有已通过审核的宠物和署名信息。安装前用它来浏览很方便。

petdex install <宠物名>

把宠物放到 ~/.codex/pets/<宠物名>/。效果等同于 curl -sSf https://petdex.dev/install/<宠物名> | sh。

petdex submit <路径>

把你的宠物发布到图库。CLI 支持三种提交形式：

• 单个文件夹：petdex submit ~/.codex/pets/boba
• 单个 zip：petdex submit ~/Downloads/boba.zip
• 批量提交：petdex submit ~/.codex/pets，每个直接子文件夹都会作为一只宠物提交

批量模式会为每只宠物显示进度，并在最后汇总失败项。宠物名会自动去重，不会因为名称已存在而提交失败。

petdex login / logout / whoami

见上面的“登录”部分。

Petdex Desktop 是一个漂浮在工作区上的桌面宠物，会根据 Agent 的工具调用做出反应。支持 macOS、Linux 和 Windows。视觉介绍见 /download。

T="$(cat "$HOME/.petdex/runtime/update-token")"
curl -X POST http://127.0.0.1:7777/state \
  -H "Content-Type: application/json" \
  -H "X-Petdex-Update-Token: $T" \
  --data-raw '{"state":"waving"}'

Living with the pet

The pet floats above every window and never steals focus. Clicks pass straight through the activity bubble to whatever is behind it, so a message appearing over your editor cannot swallow a keystroke. The sprite itself stays draggable: pick it up and drop it wherever it belongs on your screen.

Shortcuts

Hover the pet and press Cmd + , to open Settings, or Cmd + W to send it away. Both also live in the Pet menu while the app is focused.

What is in Settings

• Pets. Search your installed pets, preview each one, and switch the active pet without restarting. Every custom pet you drop in the pets folder shows up here.
• Agents. Shows which coding agents are on this machine and whether their hooks are wired. Install or disconnect any of them in one click; the app writes the hook files itself, no terminal involved.
• Appearance. Scale the sprite, and turn the activity bubble on or off if you would rather have the pet stay quiet.

ChatGPT pets

ChatGPT exports pets as a 1536x2288 spritesheet, which is exactly the atlas Petdex already reads: same nine state rows, same frame counts. A pet made there works here with no conversion.

• Bringing one in. Download the spritesheet from ChatGPT, then drop the PNG on /submit. Petdex measures the grid, generates the pet.json the export does not include, and shows an animated preview before you name it.
• Taking one out. Every pet page has an Open in Codex button that installs it into the ChatGPT desktop app. Importing straight from a ChatGPT share link is not possible: those URLs are locked to the browser session that created them.

宠物孵化出来之后，只要一条命令就能分享。完整流程如下：

1. 创建。在 ChatGPT 桌面应用中安装 Hatch Pet 技能并运行 /pet。它会把精灵图和 pet.json 生成到 ~/.codex/pets/<宠物名>/。完整教程见 /create。
2. 登录。如果还没登录，先运行 npx petdex login。
3. 提交。npx petdex submit ~/.codex/pets/<宠物名>。也可以直接提交父目录来批量提交。
4. 等待审核。提交会进入 admin queue，状态为“pending”。通过或拒绝后你会收到 Resend 邮件；如果被拒绝，邮件里会包含原因。
5. 任何人都能安装你的宠物。审核通过后，把 npx petdex install <你的宠物名> 分享给别人。他们的 ~/.codex/pets/ 里会立刻出现你的宠物。

服务器会强制执行这些规则；CLI 也会在本地提前检查。

• pet.json 和精灵图集文件 spritesheet.webp（或 .png）必须位于文件夹或 zip 根目录。
• 精灵图集 Spritesheet 至少 256×256。推荐尺寸是 1536×1872（8×9 帧网格）。
• 频率限制：每个用户 24 小时最多提交 10 次。管理员不受此限制。
• 宠物名会自动去重（boba → boba-2 → boba-3 → …）。成功提交后一定会得到可用名称。
• 身份信息（userId、email、credit）来自经过验证的 OAuth token，永远不信任请求体。

Petdex 提供兼容 Claude Code / Codex / Cursor 的 skill：.claude/skills/petdex/SKILL.md。兼容的 Agent 会自动加载它，并学会在什么场景、用什么方式替你调用 CLI。

它能做什么

• 在任意智能体工具里说“给我的智能体装个舒适系的”。它会运行 petdex list，推荐 Boba/Boxcat，安装你选的那只，并提醒你通过 Settings → Appearance → Pets 激活。
• 你可以说 “把我的所有宠物分享出去”。Agent 会在需要时运行 petdex login，再执行 petdex submit ~/.codex/pets，最后展示批量提交摘要。
• 说“我要怎么做自己的？”。智能体会带你走完 ChatGPT 桌面应用 → Hatch Pet 技能 → /pet → petdex submit。

如何启用

如果你使用 Claude Code，可以把这个 skill 保存到全局，让每个项目都能使用：

其它 Agent 工具也可以从仓库加载同一个 SKILL.md。这个文件是普通 Markdown；除了 allowed-tools 之外，没有 Agent 专属语法。

定制化自己的 skill

CLI 是可执行的操作入口，skill 是给 Agent 理解任务的认知入口。如果你想做派生 skill（例如自动给新宠物打标签，或生成每日精选），可以把 Petdex skill 当作参考。直接阅读：

.claude/skills/petdex/SKILL.md

CLI 内置了指向生产环境的默认配置。只有在测试非生产部署时，才需要覆盖环境变量。

• PETDEX_URL：基础 URL，默认 https://petdex.dev
• CLERK_ISSUER：OAuth issuer，默认 https://clerk.petdex.dev
• CLERK_OAUTH_CLIENT_ID：公开 client id（内置在 CLI 二进制文件里）

• 欢迎给这里提 PR： crafter-station/petdex
• Bug 报告和功能请求： 创建 issue
• 如果 Petdex 确实帮你省了时间，也欢迎通过 GitHub Sponsors 支持项目。