🟢 Beginner Friendly 🐾 Type: AI Coding Companion / Animated Pet Gallery 💸 Free & Open Source (MIT License) ⭐ 49 GitHub Stars
What is Petdex?
Petdex is a free, open-source gallery of over 2,900 animated pixel-art companions that you can install into your AI coding environment — things like OpenAI Codex, Claude Code, Gemini CLI, and OpenCode. Instead of staring at a cold, empty terminal while your AI agent writes code, you get a tiny animated character that lives on your screen and reacts to what your coding agent is doing.
Think of it like a Pokédex, but for AI coding pets. You browse the gallery at petdex.dev, find a companion you like — a tiny anime character, a cosy creature, a pixel-art robot, or even Pokémon-inspired designs — and install it with one single command in your terminal. The pet then appears inside your coding environment, animated and alive.
It has three parts that work together:
- The gallery website (petdex.dev) — browse and preview 2,900+ pets, filter by colour and vibe, copy the install command
- The CLI (command-line tool) — one command installs any pet directly into your coding environment
- The desktop app — floats your pet on top of your screen so you can see it while you work, reacting to your coding agent’s activity in real time
Every pet is made of two files: a pet.json file with its name and metadata, and a spritesheet image with 9 animation states (idle, running, waving, jumping, and more). All pets are community-submitted and reviewed before going live.
Who is it for?
- Developers who use AI coding agents — if you use OpenAI Codex, Claude Code, Gemini CLI, or OpenCode and want to make your sessions feel less sterile and more fun
- Anyone who loves pixel art and anime — the gallery has thousands of characters inspired by anime, games, films, and original designs
- Collectors and personalisation fans — browse and install multiple pets, switch between them, and build a personal collection
- Pixel artists and creators — if you want to design and submit your own animated pet to the public gallery and have it installed by other developers worldwide
- Students and self-taught developers who want a more welcoming, personality-filled coding environment while learning
- Open-source contributors — the whole platform is on GitHub, community-run, and accepts pull requests
What makes it special?
- 2,900+ pets and growing — the gallery has over two thousand nine hundred community-made animated companions across characters, creatures, and objects, with new ones added constantly
- One command to install —
npx petdex install bobafetches the pet and drops it straight into your coding environment. No drag-and-drop, no manual file placement - Works across multiple AI coding tools — supports OpenAI Codex, Claude Code, Gemini CLI, and OpenCode — not just one platform
- Pets react to what your agent is doing — the desktop app connects to your coding agent and changes the pet’s animation state based on activity (waiting, running, reviewing, and more)
- 9 animation states per pet — every pet has idle, run left, run right, waving, jumping, failed, waiting, running, and review states, giving it a full personality
- Filter and find exactly what you want — filter by colour (red, blue, yellow, and 10 more), vibe (cosy, playful, focused, heroic, edgy, mystical, chaotic, and more), and era (class of May 2026, June 2026)
- Curated themed collections — browse collections like Pokémon-inspired pets, League of Legends, JoJo’s Bizarre Adventure, and more — hand-curated by the Petdex team
- You can submit your own — create a pet in OpenAI Codex using the Hatch Pet skill, then submit it to the gallery with one command. Once approved, anyone can install it
- Built-in diagnostics —
npx petdex doctorchecks everything is wired correctly and gives you actionable hints if something isn’t working - Fully free, no accounts needed to browse and install — you only need to sign in if you want to submit your own pet
Requirements before you start
To install and use a pet (main use case)
- Node.js 20 or higher — the CLI runs on Node.js. Download here. Check your version by typing
node --versionin your terminal. Alternatively, it also runs on Bun if you use that - A terminal / command prompt — Mac: use Terminal. Windows: use PowerShell. Linux: any terminal
- An AI coding environment that supports pets — one of these:
- OpenAI Codex Desktop — openai.com/codex
- Claude Code — Anthropic’s CLI coding agent
- Gemini CLI or OpenCode
- Internet connection — the CLI fetches pets from Petdex’s servers when you install them
To use the floating desktop companion app (optional)
- macOS, Windows, or Linux — the desktop app works on all three
- Download link available at petdex.dev/en/download
To submit your own pet (optional, for creators)
- A Petdex account — sign in with
npx petdex login(uses your browser for authentication, no password required) - A pet.json file and a spritesheet image (WebP or PNG) with 9 animation rows — the Hatch Pet skill inside Codex Desktop generates these for you automatically
💡 Quickest start possible: If you already have Node.js and Codex installed, you can have a pet running in under 60 seconds with just one command. Skip straight to Step 3 below.
Step-by-step setup
Part 1 — Browse and install a pet 🐾
Step 1 — Check your Node.js version
Open your terminal and run:
node --versionYou need v20.x.x or higher. If your version is older, download Node.js 20+ from nodejs.org and install it before continuing.
Step 2 — Browse the gallery and pick a pet
Go to petdex.dev in your browser. You’ll see over 2,900 animated pets in a scrollable gallery.
Use the filters on the left to narrow it down:
- Color — filter by the pet’s main colour (red, blue, yellow, green, pink, and more)
- Vibe — filter by personality: cosy, playful, focused, heroic, edgy, calm, mystical, chaotic, wholesome
- Era — see which “class” of pets was submitted (Class of May 2026, June 2026, etc.)
Click on any pet to open its detail page. There you can preview all 9 animation states — watch it idle, run, wave, jump, and more.
Step 3 — Install your pet with one command
On any pet’s detail page you’ll see an install command. Copy it and paste it into your terminal. For example, to install the pet called Boba:
npx petdex install bobaReplace boba with the slug (name) of whatever pet you chose. The CLI will download the pet and drop it into ~/.codex/pets/boba/ automatically.
You can also browse and install directly from the terminal without ever opening the website:
npx petdex listStep 4 — Activate the pet in your coding environment
For OpenAI Codex:
- Open Codex Desktop
- Go to Settings → Appearance → Pets
- Find the pet you just installed and click Select
- Type
/petin any Codex chat to wake or tuck away your companion
For Claude Code or other agents:
After installing, run the select command to set it as active:
npx petdex selectFollow the interactive menu to choose your pet. The CLI will wire it to your supported agent automatically.
Step 5 — (Optional) Install globally so you don’t need npx every time
If you’ll be using Petdex often, install it globally so you can just type petdex instead of npx petdex:
npm install -g petdexNow you can run any command without the npx prefix:
petdex install doraemon
petdex list
petdex selectStep 6 — (Optional) Install and run the Petdex Desktop app
The desktop app floats your pet on top of all your windows so you can see it while you work, reacting to your coding agent’s activity in real time.
Download it from: petdex.dev/en/download
Or trigger the download and start it through the CLI:
npx petdex startThis downloads the desktop app, starts it, and automatically wires it to your supported agents. Your pet will now float on your screen and animate based on what your AI agent is doing.
Step 7 — (Optional) Run a health check
If anything seems off — the pet isn’t showing, animations aren’t triggering, or the desktop app isn’t connecting — run the built-in doctor command:
npx petdex doctorThis checks your setup end-to-end: the binary, sidecar connection, token status, agent hooks, Codex feature flags, and pet count. Any failed check comes with an actionable hint telling you exactly how to fix it.
Part 2 — Create and submit your own pet 🎨 (optional, for creators)
Step 1 — Generate your pet in Codex
- Open Codex Desktop
- Go to Skills in the top navbar
- Find and install the Hatch Pet skill
- In any Codex chat, type
/petfollowed by a description — for example:/pet a tiny otter sipping bubble tea - Codex will generate the spritesheet and all animation states, saving them to
~/.codex/pets/<slug>/
Step 2 — Sign in to Petdex
npx petdex loginThis opens your browser for authentication. No password — it uses a secure OAuth flow. Your tokens are stored safely in your OS keychain.
Step 3 — Submit your pet
npx petdex submit ~/.codex/pets/your-pet-slugThe CLI uploads your pet.json and spritesheet to Petdex’s servers and queues your submission for review. You’ll receive an email when it’s approved (or rejected with a reason).
Once approved, anyone in the world can install your pet with:
npx petdex install your-pet-slugCommon errors and fixes
| Error | What it means | How to fix it |
|---|---|---|
node: command not found | Node.js is not installed or not in your PATH | Download and install Node.js 20+ from nodejs.org, then restart your terminal and try again |
npx petdex install boba completes but pet doesn’t appear in Codex | The pet was installed but not yet activated in your coding environment | Open Codex → Settings → Appearance → Pets → find your pet and click Select. Or run npx petdex select from your terminal |
| Pet installed but animations don’t react to agent activity | The Petdex desktop app sidecar is not running or not connected | Run npx petdex doctor — it will identify the exact issue. Usually solved by running npx petdex start to launch the desktop sidecar |
Pet not found: slug-name | The pet slug is misspelled or the pet hasn’t been approved yet | Check the exact slug on petdex.dev — it appears in the URL of the pet’s page. Slugs are lowercase with hyphens (e.g. noir-webling) |
npx petdex login browser tab opens but never completes | OAuth callback was blocked or the browser closed too early | Make sure your default browser is open before running the command. Complete the login in the browser window that opens — don’t close it until you see a “success” message |
| Submission stuck in “pending” for a long time | All submissions go through manual review by a Petdex admin | This is normal — review times vary. You’ll receive an email when approved or rejected. Join the Petdex Discord if you want to follow up |
| Desktop app won’t start or crashes immediately | Outdated version of the desktop app, or a pid file conflict | Run npx petdex update to download the latest version. This stops the old app, swaps the binary, and restarts it automatically |
petdex: command not found after global install | npm global bin directory is not in your PATH | Restart your terminal. If it still fails, use npx petdex instead — it always works without a global install |
Free vs Paid comparison
Petdex is completely free — both the gallery and the CLI. There is no paid tier. Here is how it compares to other ways of personalising your AI coding environment:
| Feature | Petdex (Free) | Paid / Premium Alternatives |
|---|---|---|
| Cost | $0 — fully free | Varies — often $5–$20+/month for avatar customisation in coding tools |
| Number of pets / companions | 2,900+ and growing | Usually a handful of official options |
| Community-submitted designs | ✅ Yes — open submissions | ❌ Usually only official designs |
| One-command install | ✅ npx petdex install slug | Varies — often manual file placement |
| Animated states (9 per pet) | ✅ Yes — idle, run, wave, jump, review, and more | Varies — some tools only have static avatars |
| Reacts to coding agent activity | ✅ Yes — via desktop app + sidecar | Rarely available |
| Works across multiple AI tools | ✅ Codex, Claude Code, Gemini CLI, OpenCode | Usually locked to one platform |
| Submit your own designs | ✅ Yes — free to submit | ❌ Usually closed |
| Open source | ✅ MIT License — full source on GitHub | ❌ Usually proprietary |
Bottom line: Petdex is the only place to get 2,900+ animated AI coding companions for free, installable in one command, with community submissions open to anyone. There is simply no paid equivalent that comes close to this scale and openness.
Alternatives — 3 similar tools
1. Tamagotchi-style desktop pets (Shimeji)
Shimeji is a long-running free tool that lets animated characters (originally from Japanese anime) walk around your desktop screen. Thousands of community-made characters exist. Unlike Petdex it doesn’t connect to AI coding agents, but if you want a desktop companion that doesn’t require any AI tools, Shimeji is the classic choice.
2. Taiko no Tatsujin Desktop Mascots (community)
A niche but popular community of pixel desktop mascots based on game characters. Standalone animated companions that sit on your screen. No AI or coding agent integration, but a great source of animated sprite companions if you want to explore the pixel-art desktop pet format more broadly.
🔗 github.com/topics/desktop-pet
3. PetsCodex
A separate community-built gallery for Codex pets — similar concept to Petdex, also free and browser-based. Smaller catalog than Petdex but another good source of companions and install commands if you want to browse an alternative collection. Both work with the same Codex pet format.
🚀 Want more free AI tools like this?
We find, test, and write plain-English setup guides for the best free and open-source AI tools — so you don’t have to dig through GitHub yourself.Browse Free AI Tools at globalaiforce.com/shop →
📸 Follow us for daily AI tool tips and tutorials: instagram.com/globalaiforce