Docs

Follow this checklist to get a pet installed, visible in Codex, and connected to the desktop app. No account required to install. Sign in only when you submit.

1. 1

   Install a known pet

   Start with Boba so you have a real pet folder to select in Codex.

   You should see ~/.codex/pets/boba/ with pet.json and a spritesheet.

   $ npx petdex install boba
2. 2

   Initialize desktop and hooks

   Run the full setup when you want the floating desktop mascot and agent activity hooks.

   Pet Pepper downloads the desktop app, starts it, and wires supported agents for /petdex.

   $ npx petdex init
3. 3

   Select the pet in Codex

   Open Codex, go to Settings → Appearance → Pets, choose Boba, and click Select.

   Use /pet inside Codex to wake the pet or tuck it away.

4. 4

   Verify the setup

   Run diagnostics if the pet does not appear, or type /petdex status inside a supported agent after hooks are installed.

   The doctor reports any missing binary, hook, token, or pet folder with a concrete fix.

   $ npx petdex doctor

The CLI runs on Node 20+ (or Bun). Pick the workflow that fits you. Both are equivalent in capability and persistence.

Casual / one-off

Use npx. No setup, package is cached after first run.

Power user

Install globally for instant invocation and easier muscle memory.

Auth persistence is identical in both. Tokens live in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) under the service name petdex-cli. Even if npx clears its package cache, your session survives.

Sign in once, then any command that needs auth, such as submit, works seamlessly.

The flow is OAuth 2.0 + PKCE: the CLI opens your browser, you sign in with Clerk on accounts.pet-pepper.example, and the browser redirects to a one-shot localhost listener with the authorization code. The CLI exchanges it for a token set and stores it in the keychain. No secrets touch disk.

Other auth commands:

The CLI covers the full lifecycle: discover, install, hatch, publish, plus the desktop app and agent hooks. All commands accept --help.

petdex list

Print every approved pet with credit. Useful for discovery before installing.

petdex install [slug]

Drop a pet into ~/.codex/pets/[slug]/. Equivalent to curl -sSf https://pet-pepper.example/install/[slug] | sh.

petdex submit [path]

Publish your pet(s) to the gallery. The CLI accepts three shapes:

• Single folder: petdex submit ~/.codex/pets/boba
• Single zip: petdex submit ~/Downloads/boba.zip
• Bulk: petdex submit ~/.codex/pets: every direct subfolder is treated as its own pet

Bulk mode shows a progress spinner per pet and a final summary of failures. Slugs auto-deduplicate so you will not hit a slug-taken bounce.

petdex login / logout / whoami

See the Authenticate section above.

Pet Pepper Desktop is a floating mascot that lives on top of your workspace and reacts to your coding agent tool calls. macOS today, Linux and Windows soon. See /download for the visual tour.

petdex install desktop

Fetches the latest binary from GitHub Releases for your platform and drops it at ~/.petdex/bin/petdex-desktop. The CLI strips the macOS quarantine attribute so the app opens without a Gatekeeper prompt.

petdex hooks install

Wires the desktop app into your coding agents so the pet animates as you work. Picks the agents present on your machine and writes hooks for each:

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

Tool events map to pet states: tool.before → running, tool.after → idle, session.end → waving, session.error → failed. Each hook POSTs to the local sidecar at http://127.0.0.1:7777/state.

petdex desktop <start | stop | status>

Manage the running pet. start spawns it detached (PID at ~/.petdex/desktop.pid, log at ~/.petdex/desktop.log). stop sends SIGTERM. status reports running, stopped, or stale.

petdex up / down / toggle

One-shot wake/sleep for the mascot. up enables hooks AND launches the desktop. down disables hooks AND stops the desktop. toggle flips between them based on current state. That is what the /petdex slash command runs from inside your agent.

/petdex (slash command)

Once petdex hooks install has run, every supported agent (Claude Code, Codex, Gemini, OpenCode) gets a /petdex command in its picker. Type it inside the agent and the mascot wakes or sleeps without leaving the chat:

• /petdex: toggle (wake if asleep, sleep if awake)
• /petdex up: force-wake
• /petdex down: force-sleep
• /petdex status: show whether hooks are enabled
• /petdex doctor: diagnose install + agent wiring

petdex hooks (kill-switch)

Even with hooks installed, you can pause them without touching your agent settings. petdex hooks off drops a flag file at ~/.petdex/runtime/hooks-disabled; every installed hook checks for it first and exits 0 immediately. petdex hooks on removes the file. Useful when a sidecar has gone weird and you do not want stray curls in your agent log.

petdex hooks uninstall

Reverses hooks install: removes the petdex entries from each agent config (preserving your own hooks), deletes the /petdex slash command files, and removes the OpenCode plugin. Pass --remove-token to also drop the auth token at ~/.petdex/runtime/update-token.

petdex doctor

Diagnostic. Verifies binary, sidecar bundle, sidecar reachability, pid file format, token mode, kill-switch state, hooks installed in each agent, Codex codex_hooks feature flag, and usable pet count. Each failed check ships an actionable hint.

petdex update

Compares your installed version against the latest GitHub Release tag and downloads it if newer. If the desktop app was running, it stops it, swaps the binary, and restarts. Pass --force to re-download the same version.

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

Once you have hatched a pet inside Codex, sharing it takes one command. Here's the full lifecycle:

1. Create. In Codex Desktop, install the Hatch Pet skill and run /pet. Codex generates the spritesheet and pet.json into ~/.codex/pets/[slug]/. Full tutorial at /create.
2. Sign in. npx petdex login if you have not.
3. Submit. npx petdex submit ~/.codex/pets/[slug]. Or bulk all at once with the parent dir.
4. Wait for review. Submissions land as “pending” in the admin queue. You will receive a Resend email when approved or rejected (if rejected, the reason is included).
5. Anyone can install your pet. Once approved, share npx petdex install [your-slug] with anyone. They get your pet in their ~/.codex/pets/ instantly.

The server enforces these rules; the CLI checks locally too.

• pet.json and spritesheet.webp (or .png) must be at the root of the folder/zip.
• Spritesheet ≥ 256×256. Recommended 1536×1872 (8×9 frame grid).
• Rate limit: 10 submissions / 24h per user. Admins bypass.
• Slugs auto-deduplicate (boba → boba-2 → boba-3 → …). You always get a successful submission.
• Identity (userId, email, credit) comes from the verified OAuth token. Never trusted from request body.

Pet Pepper ships a Claude Code / Codex / Cursor compatible skill at .claude/skills/petdex/SKILL.md. Compatible agents load it automatically and learn when and how to call the CLI on your behalf.

What this enables

• Say “install something cozy for my Codex” in any agent tool. It runs petdex list, suggests Boba/Boxcat, installs your pick, and reminds you to activate via Settings → Appearance → Pets.
• Say “share all my pets”. Agent runs petdex login if needed, then petdex submit ~/.codex/pets, surfaces the bulk summary.
• Say “how do I make my own?”. Agent walks you through Codex Desktop → Hatch Pet skill → /pet → petdex submit.

How to enable it

If you use Claude Code, save the skill globally so every project has it:

Other agent tools can load the same SKILL.md from the repo. The file is plain markdown. No agent-specific syntax beyond allowed-tools.

Build your own skill on top

The CLI is the executable surface; the skill is the cognitive one. If you build a derivative skill (for example, one that auto-tags new pets or curates a daily digest), you can use the Pet Pepper skill as a reference. Read it directly:

.claude/skills/petdex/SKILL.md

The CLI ships with sensible defaults pointing at production. You only need to override env vars if you are testing against a non-production deployment.

• PETDEX_URL: base URL, default https://pet-pepper.example
• CLERK_ISSUER: OAuth issuer, default https://clerk.pet-pepper.example
• CLERK_OAUTH_CLIENT_ID: public client id (baked into the CLI binary)

• PRs welcome at henryjing96/pet-pepper-platform
• Bug reports and feature requests: open an issue
• Sponsor on GitHub Sponsors if Pet Pepper saves you time.