About

Petdex is the index of Codex pets

An open-source gallery of 99+ animated pixel companions for the Codex CLI. Install one with a single command, animate your terminal, and ship code with company.

What Petdex is

Petdex is a public, open-source registry. Every entry is a pet pack — a tiny bundle of metadata and pixel art that the Codex CLI knows how to display while you work. Think of it as a Pokédex for terminal companions.

The platform takes the guesswork out: there's a CLI for installing and submitting, a tagged gallery so finding the right companion doesn't require scrolling, and per-vibe collections like cozy pets or focused pets.

How a pet pack works

Each pet is two files. pet.json defines the metadata — name, the 9 animation states, frame durations — and spritesheet.webp holds the pixel art as a horizontal strip. Codex loads them at startup and swaps states based on what's happening in your session.

FAQ

What is a Codex pet?

A Codex pet is a small animated pixel companion that lives inside the Codex CLI. Each pet ships as a single pet.json describing 9 states (idle, working, sleeping, etc.) plus a horizontal spritesheet. Codex picks the right state automatically based on what you're doing in the terminal.

How do I install a pet?

From the gallery page or any pet detail page, copy the install command (looks like `npx petdex install boba`) and paste it into your terminal. The CLI fetches the pet from R2, drops it under ~/.codex/pets/<slug>/, and tells Codex to use it. Works on macOS, Linux, and Windows (via PowerShell).

Where do the pets come from?

Most pets are submitted by the community through the website or the petdex CLI. A handful are featured curated entries hand-picked from Crafter Station. Every pet is reviewed by an admin before it goes live in the gallery.

Can I submit my own pet?

Yes. Sign in with the petdex CLI (npx petdex login) and run `npx petdex submit ./my-pet/` — the CLI uploads the assets to R2 and queues the submission for review. You can also submit through the website at /submit. All you need is a pet.json file and a 9-state spritesheet.

Are Petdex pets free and open source?

Every pet on Petdex is free to install and use. Pets keep credit to their original authors. The Petdex platform itself (CLI + site) is open source under the Crafter Station umbrella.

What's a vibe? What's a kind?

Each pet is tagged with a kind (creature, object, character) and one to three vibes (cozy, playful, focused, mystical, …). These power the gallery filters and the per-vibe / per-kind landing pages so you can find a companion that matches your mood without scrolling 70+ entries.

How does Petdex make money?

It doesn't. Petdex is a community project run by Crafter Station. Storage and DB are absorbed by the platform team — no ads, no upsells, no telemetry beyond standard analytics on which pets get installed.