Petdex: A Gallery, CLI, and Desktop Floater for Coding Agent Mascots

What Petdex Solves and Who It Is For

Petdex addresses a narrow but real problem: coding agents are invisible while they work. You watch a terminal or a log stream, but there is no ambient signal for what the agent is doing. Petdex turns that activity into an animated pet floating over your workspace. The pet reacts to tool calls with states like running, jumping, failed, and waiting. This is for developers who spend hours with an agent and want a lightweight, non-intrusive status indicator that is also fun. It is not for teams or production monitoring; it is a personal tool. The README positions it as three things working together: a web gallery, a CLI, and a desktop app. The gallery is the community hub for browsing and submitting pets. The CLI installs any pet into Codex. The desktop app is where the animation happens. The target user is an individual developer who uses one of the listed agents and wants a mascot that mirrors their work.

How the Pieces Fit: Gallery, CLI, and Desktop App

The architecture is split into three surfaces. The web gallery at petdex.dev is a Next.js 16 app with React 19, Tailwind, Drizzle, Postgres, Redis, Clerk, and R2. It has routes for the gallery, individual pet pages, collections, a built-with catalog, and a submit flow. The CLI is a Bun and TypeScript package that ships as a single npm binary. It handles installation and submission, with auth via Clerk OAuth and PKCE. The desktop app is a native SDK application with an in-process Zig hook server on 127.0.0.1:7777. The README explicitly notes that the current release path has no WebView or Node sidecar, which is a deliberate choice to keep the app lightweight. The desktop app connects to your coding agents and animates the pet on every tool call. The data flow is: the agent emits activity, the Zig hook server captures it, and the desktop app maps that activity to animation states. The CLI installs a pet into ~/.petdex/pets/ with a pet.json and spritesheet, and the desktop app reads from that same directory.

Getting a Pet Installed and Running

The README gives a clear quick start. First, install a known pet with `npx petdex install boba`. This creates `~/.petdex/pets/boba/` containing `pet.json` and a spritesheet. Then download the desktop app from petdex.dev/download, which runs on macOS, Linux, and Windows. Open the app, press Cmd+, to open Settings, pick your pet under Pets, and connect your coding agents under Agents with one click each. No terminal is needed for the desktop app after the initial CLI install. For browsing, you visit petdex.dev. To switch the active mascot, you use the desktop app's Settings. To create a pet, you use the `hatch-pet` skill inside Codex or the creator tools at petdex.dev/create. To submit a pet, you run `npx petdex submit ./my-pet/` or use the web submitter. The CLI reference lives in packages/petdex-cli/README.md, which is not included in the material, so the full command set beyond install and submit is not confirmed.

The Pet Package Format and Its Constraints

Every pet is a folder with two files: `pet.json` for metadata and a spritesheet in webp or png format. The spritesheet is an 8x9 grid of 192x208 pixel frames, or the v2 8x11 grid. 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. This is a concrete constraint: if you want a custom animation state beyond the nine, you need the v2 format and a client that knows how to read row ten and eleven. The frame size is fixed, so pets are not responsive to different screen densities. The format is simple, which is a strength for portability, but it also means you cannot have variable frame rates or per-frame timing metadata. The README does not mention any timing or loop configuration, so animations are likely fixed at a default speed.

The HTTP API and the Built-With Ecosystem

For builders, Petdex offers two stable surfaces. The HTTP API at petdex.dev/api/manifest returns every approved pet with its slug, spritesheet URL, animation states, and metadata. This is a public endpoint that any client can consume. The second surface is the pet package format itself, which is just a folder with two files. The README claims that 21 open-source and source-available projects already build on these surfaces, and there is a built-with catalog at petdex.dev/built-with. To list your project, you open a Built with Petdex issue using a template. This is a real integration point: you could build a different desktop client, a wearable, an SDK, or a Discord bot that reads the manifest and renders pets. The API is read-only for the manifest, with separate endpoints for CLI operations like submit and dedup check. The admin review surface is separate, so the public API is clean. The limitation is that the manifest only includes approved pets, so community submissions go through a review process before they appear.

The Desktop App's Zig Hook Server: A Trade-off

The desktop app uses an in-process Zig hook server on 127.0.0.1:7777. This is an unusual design. Most similar apps use a Node sidecar or a WebView to interact with agents. Petdex avoids both, which makes the app lighter and faster to launch. The Zig server listens on a localhost port, presumably to receive activity events from the coding agents. The trade-off is security: a local server on a fixed port could be a target for other local processes. The README does not describe any authentication or access control for that port, so any process on your machine could potentially send fake events. For a desktop app that is meant to be fun, this is acceptable, but it is a real consideration for security-conscious users. The README also notes that the current release path has no WebView or Node sidecar, which means the UI is native and the hook server is the only bridge. This is a deliberate architectural choice that trades flexibility for simplicity.

Limitations and When Petdex Is the Wrong Tool

Petdex has clear boundaries. It is not a productivity tool in the traditional sense; it is a cosmetic addition. If you use an agent that is not Codex, Claude Code, OpenCode, or Gemini CLI, the README does not list support for others, so the desktop app may not react to your agent. The pet format's fixed frame size and nine-state limit could be restrictive for complex animations. The desktop app requires a download and manual setup, which is more friction than a pure CLI tool. The takedown policy is reactive: if you hold rights to a character, you file a request and they review within 48 hours, but there is no proactive IP filtering. For a user who wants a serious status indicator with detailed logs or metrics, Petdex is the wrong tool because it only shows animation states, not text or numbers. The README does not mention any way to customize the animation speed or the mapping between agent events and states, so you are stuck with the default behavior unless you build your own client.

Alternatives and the Difference in Approach

The obvious alternative is to build your own status indicator using the agent's native hooks or a terminal plugin. For example, you could write a script that watches your agent's log output and changes a terminal color or icon. That approach gives you full control over the data and the display, but it requires coding effort and offers no visual polish. Another alternative is to use a generic desktop pet app that does not integrate with coding agents; those exist, but they do not react to agent activity, so you lose the core value. The actual difference with Petdex is the integration layer: the desktop app's Zig hook server connects directly to agent activity, so the pet animates on every tool call without you writing any glue code. The CLI and the manifest API also provide a standard format, so you can share pets across the ecosystem. If you want that integration without building it yourself, Petdex is the turnkey option. If you want to control every aspect of the indicator, you are better off with a custom script.

Maintenance, Licensing, and Upgrade Path

The source code is MIT, but pet assets are owned by their submitters under whatever license they declare. That means you can use and modify the code freely, but the pets themselves may have separate license terms. The README does not specify a maintenance policy, but the recent release history shows active development: desktop-v0.8.0 on 2026-08-14, desktop-v0.7.0 the day before, and cli-v1.2.2 the same day. That suggests frequent updates. The upgrade path is straightforward: the CLI is an npm package, so you can update it with your package manager, and the desktop app has a download page. The v2 spritesheet format is a potential upgrade consideration, since it adds two rows for clients to use. The README does not mention any migration tooling for converting pets from the 8x9 to the 8x11 format, so existing pet creators may need to re-render. For consumers, the CLI installs into a fixed directory, so upgrading the CLI should not break existing pets.

Editorial conclusion

Adopt Petdex if you use Codex, Claude Code, OpenCode, or Gemini CLI and want a visual, reactive companion that animates on tool calls. Skip it if you have no interest in desktop mascots or if you need a web-only solution, since the desktop app is where the real-time reaction happens. Before adopting, verify that the desktop app's in-process Zig hook server on 127.0.0.1:7777 does not conflict with your security policies, and check the pet package format's nine state rows against your agent's activity hooks, since the v2 8x11 atlas leaves only two extra rows for custom states.

Official sources

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