Petdex: animated pets for Codex, Claude Code, OpenCode and Gemini CLI

What Petdex actually solves for agent users

A coding agent running in a terminal is opaque. It reads files, calls tools, waits on a model, and fails, and the only feedback is scrolling text. Petdex turns that activity into a sprite animation: the pet idles when nothing is happening, runs when a tool call fires, waves, jumps, or switches to a failed state when a call errors. The README lists nine state rows the native renderer supports: idle, running-right, running-left, waving, jumping, failed, waiting, running, and review. Codex and the other supported agents map their activity hooks onto those rows.

The audience is narrow and clearly stated. Petdex is for people who already run Codex, Claude Code, OpenCode or Gemini CLI and want a persistent, glanceable indicator of what the agent is doing. It is also for artists who want a distribution channel: every pet is a folder, every folder is a Pokédex entry, and submission goes through the web submitter or a CLI command. The project does not try to be a general desktop mascot framework, and the README never claims it is.

How the gallery, CLI and desktop floater fit together

The repository is a Next.js 16 monorepo with three surfaces that share one data model. The public site serves the gallery, individual pet pages at /pets/<slug>, collections, the built-with catalog, and the submit flow. The CLI lives in packages/petdex-cli, is written in Bun and TypeScript, and ships as a single npm binary. The desktop app is a native SDK application with an in-process Zig hook server listening on 127.0.0.1:7777; the README states the current release path has no WebView or Node sidecar.

The data flow is straightforward. A pet is a pet.json plus a spritesheet rendered as an 8x9 grid of 192x208 frames, or the v2 8x11 grid. The web app stores approved pets in Postgres through Drizzle and serves them from petdex.dev/api/manifest, which returns each approved pet with its slug, spritesheet URL, animation states and metadata. The CLI pulls from that surface and writes the folder locally. The desktop app reads the local folder and animates it, driven by hooks from whichever agent you connected.

That separation is the design's strongest point. The manifest is a public HTTP endpoint, so a third party can build a client without touching the Next.js code. The README says 21 open-source and source-available projects already build on those two surfaces, and points to petdex.dev/built-with for the catalog. The pet format itself is the contract: two files, a fixed frame size, a fixed grid, and a documented set of state rows.

Installing a pet and seeing it move

The README's quick start is three steps. First, install a known pet from npm. The command is run with npx, so nothing is installed globally.

npx petdex install boba

According to the README, you should see ~/.petdex/pets/boba/ containing pet.json and a spritesheet. If that directory does not appear, the install did not complete, and the CLI reference in packages/petdex-cli/README.md is the place to look rather than the top-level README.

Second, get the desktop app from petdex.dev/download. It runs on macOS, Linux and Windows. Third, open it and press Cmd+, over the pet to open Settings. Under Pets you pick the active pet; under Agents you connect your coding agents, one click each, with no terminal involved. The README states the pet floats above your workspace and animates on every tool call your agent makes.

If you would rather run the whole stack yourself, the repository supports a container path. The commands below come from the README's develop-locally section and the package.json scripts.

git clone https://github.com/crafter-station/petdex.git
cd petdex
bun install
bun run dev:docker

The README says dev:docker needs Docker or Podman and about 30 seconds of warm-up, and that localhost:3000 serves the site. A second path, bun run dev, runs against real services and requires a filled .env.local; the README marks that path as maintainers only. The .env.example file confirms the split: dev:docker uses committed defaults from .env.dev, and anything in .env.local overrides them.

The pet format is the part worth building on

The README is unusually specific about the package format, and that specificity is what makes the project useful beyond its own desktop app. A pet is a directory containing pet.json and a spritesheet.webp (or .png). The spritesheet is an 8x9 grid of 192x208 pixel frames, or the v2 8x11 grid. The nine state rows are named, not positional guesses, and the README notes that the v2 atlas leaves two additional rows available to the consuming client.

For anyone writing a renderer, that is enough to start. For anyone writing an agent integration, it is not: the README says Codex and the supported agents map their activity hooks to these states, but it does not document the hook names or the mapping. The desktop app performs that mapping internally. A third-party client that wants the same behaviour has to infer it or read the source.

There are repository scripts that suggest the maintainers treat the atlas as something to validate rather than trust. package.json includes audit:pet-atlases, which runs scripts/audit-pet-atlases.ts with an --all flag. The existence of that script implies malformed atlases reach the review pipeline often enough to need an automated check. The README does not describe what the audit rejects.

Where Petdex is the wrong tool

The desktop app is the weakest documented surface. The README covers the happy path in three sentences and stops. There is no documented configuration file, no environment variable list for the desktop binary, and no stated way to point it at a self-hosted manifest instead of petdex.dev. The port 127.0.0.1:7777 is mentioned as the hook server address, but the README does not describe the protocol, the endpoints, or whether the server binds beyond localhost. If your threat model includes other processes on the same machine talking to that port, you have no documented answer.

Pet assets carry a second risk that the README states plainly. Pets are user-submitted fan art, Petdex does not claim rights to any underlying IP, and takedowns are reviewed within 48 hours. A pet you install today can disappear from the gallery tomorrow. The MIT licence covers the source code only; the README says pet assets are owned by their submitters under whatever licence they choose to declare.

Finally, this is a cosmetic layer. If your agent is failing silently, a pet switching to its failed state is a weaker signal than reading the tool output. Petdex adds a visual channel, not a diagnostic one, and nothing in the README suggests it logs or replays agent activity.

Alternatives and the difference in approach

The obvious alternative is to write your own hook script that prints status to your terminal prompt or a tmux status line. That approach is more work to set up and gives you no art, but it is fully scriptable, it has no local server listening on a port, and it does not depend on a remote manifest staying online. Petdex's desktop app is the opposite trade: near-zero setup, a fixed visual vocabulary of nine states, and a dependency on petdex.dev for discovery.

A second alternative is building directly on the two surfaces the README names, the HTTP manifest and the pet package format, and skipping both the CLI and the desktop app. That is what the 21 projects listed at petdex.dev/built-with have done. You get the same pet data with none of the desktop app's undocumented behaviour, at the cost of writing the renderer and the hook mapping yourself. For a Discord bot or a wearable, that is the sensible route; for a developer who just wants a sprite on their screen, it is strictly more work than npx petdex install boba.

Maintenance, releases and licence cost

The repository is not archived, and the last push was on 2026-08-14. The most recent releases are petdex-desktop v0.8.0 on 2026-08-14, petdex-desktop v0.7.0 on 2026-08-13, and petdex CLI v1.2.2 on 2026-08-13. The CLI and desktop app are versioned separately, which matters: a desktop release does not imply a CLI release, and the two can drift.

Upgrade cost for the CLI is low. It ships as a single npm binary invoked through npx, so there is no global state to migrate beyond the pet folders under ~/.petdex/pets/. The desktop app is a native download, so upgrading means reinstalling from petdex.dev/download; the README does not document an in-app updater or a rollback path.

On licence: the source is MIT, which permits commercial use and modification. That does not extend to the art. The README states that pet assets are owned by their submitters under whatever licence they declare, and that Petdex does not claim rights to any underlying IP. If you plan to ship a pet inside a product, the pet.json metadata is where the submitter's declared licence lives, and nothing in the README guarantees that declaration is accurate. That is a diligence problem for you, not a legal conclusion.

Editorial conclusion

Adopt Petdex if you already run Codex, Claude Code, OpenCode or Gemini CLI and want a visual signal of agent activity that costs one npx command and no configuration files. Skip it if you need a documented, scriptable way to point the desktop app at a self-hosted manifest, or if you are building a product on the pet format and need a stability guarantee the README does not give. Before installing, check the manifest endpoint at petdex.dev/api/manifest and confirm the pet you want is listed there; before submitting art, read the takedown section, because Petdex states it does not claim rights to any underlying IP and removes entries on request within 48 hours.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes