文档

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

1. 1

   先安装一只已知宠物

   建议先用 Boba，这样 Codex 里一定有一个可以选择的宠物目录。

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

   $ npx petdex install boba
2. 2

   初始化桌面应用和 hooks

   如果你想让宠物浮在桌面上，并响应 coding agent 的活动，就运行完整初始化。

   Pet Pepper 会下载并启动桌面应用，同时给支持的 agent 接上 /petdex。

   $ npx petdex init
3. 3

   在 Codex 里选择宠物

   打开 Codex，进入 Settings → Appearance → Pets，选择 Boba，然后点击 Select。

   在 Codex 里使用 /pet 可以唤醒宠物，也可以把它收起来。

4. 4

   验证配置是否正常

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

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

   $ npx petdex doctor

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

快速安装

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

全局安装

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

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

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

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

其它登录相关命令：

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

petdex list

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

petdex install [宠物名]

把宠物放到 ~/.codex/pets/[宠物名]/。效果等同于 curl -sSf https://pet-pepper.example/install/[宠物名] | sh。

petdex submit [路径]

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

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

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

petdex login / logout / whoami

见上面的“登录”部分。

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

petdex install desktop

从 GitHub Releases 拉取适合当前平台的最新二进制文件，并放到 ~/.petdex/bin/petdex-desktop。CLI 会移除 macOS quarantine 属性，让应用打开时不再触发 Gatekeeper 提示。

petdex hooks install

把桌面应用接入你的 Agent，让宠物在你工作时摇摆。CLI 会识别本机已有的 Agent，并分别写入 hooks：

• Claude Code: ~/.claude/settings.json
• Codex CLI: ~/.codex/hooks.json
• Gemini CLI: ~/.gemini/settings.json
• OpenCode: ~/.config/opencode/plugins/petdex.js

工具事件会映射到宠物状态：tool.before → running，tool.after → idle，session.end → waving，session.error → failed。每个 hook 都会 POST 到本地 sidecar：http://127.0.0.1:7777/state。

petdex desktop <start | stop | status>

管理正在运行的宠物。start 会以 detached 方式启动（PID 在 ~/.petdex/desktop.pid，日志在 ~/.petdex/desktop.log）。stop 发送 SIGTERM。status 显示 running、stopped 或 stale。

petdex up / down / toggle

一次性切换桌面宠物的 wake 或 sleep 状态。up 会启用 hooks 并启动 desktop；down 会禁用 hooks 并停止 desktop；toggle 根据当前状态切换。这也是你在 Agent 里运行 /petdex 时触发的命令。

/petdex （斜杠命令）

运行过 petdex hooks install 后，每个受支持的 Agent（Claude Code、Codex、Gemini、OpenCode）都会获得 /petdex 命令。你可以在 Agent 里直接输入它，让宠物 wake 或 sleep，不需要离开当前对话：

• /petdex：切换状态（sleep 时切到 wake，wake 时切到 sleep）
• /petdex up：切到 wake 状态
• /petdex down：切到 sleep 状态
• /petdex status：查看 hooks 是否启用
• /petdex doctor：诊断安装和 Agent 接入状态

petdex hooks （开关）

即使已经安装 hooks，也可以暂停它们，而不必改动 Agent 配置。petdex hooks off 会在 ~/.petdex/runtime/hooks-disabled 写入一个标记文件；所有已安装 hook 都会先检查它，命中后直接退出 0。petdex hooks on 会删除这个文件。适合 sidecar 异常时临时停用。

petdex hooks uninstall

撤销 hooks install：从每个 Agent 配置中移除 petdex 项（保留你自己的 hooks），删除 /petdex 斜杠命令文件，并移除 OpenCode 插件。传入 --remove-token 还会删除 ~/.petdex/runtime/update-token 里的 auth token。

petdex doctor

诊断命令。会检查二进制文件、sidecar bundle、sidecar 可达性、pid 文件格式、token 权限、kill-switch 状态、各 Agent 是否安装 hooks、Codex 的 codex_hooks feature flag，以及可用宠物数量。每个失败项都会给出可执行的提示。

petdex update

比较本机已安装版本和最新 GitHub Release tag，如果有更新就下载。若桌面应用正在运行，会先停止、替换二进制，再重新启动。传入 --force 可以重新下载同一版本。

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"}'

在 Codex 里孵化好宠物之后，一条命令就能分享出去。完整流程如下：

1. 创建。在 Codex Desktop 里安装 Hatch Pet skill，然后运行 /pet。Codex 会把精灵图集 Spritesheet 和 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，永远不信任请求体。

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

它能做什么

• 你可以在任意 Agent 工具里说 “给我的 Codex 装一个舒服点的宠物”。它会运行 petdex list，推荐 Boba/Boxcat，安装你选中的宠物，并提醒你到 Settings → Appearance → Pets 启用。
• 你可以说 “把我的所有宠物分享出去”。Agent 会在需要时运行 petdex login，再执行 petdex submit ~/.codex/pets，最后展示批量提交摘要。
• 你可以问 “我怎么做自己的宠物？”。Agent 会带你走完整流程：Codex Desktop → Hatch Pet skill → /pet → petdex submit。

如何启用

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

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

定制化自己的 skill

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

.claude/skills/petdex/SKILL.md

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

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

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