Summary

Petdex provides a vibrant, community-driven platform for animated companions designed to enhance the experience of using AI coding agents like Codex, Claude Code, and Gemini CLI. It offers a centralized web gallery for browsing, installing, and submitting these animated pets, alongside a convenient command-line interface (CLI) for seamless integration directly into coding environments. The project aims to bring visual personality and real-time feedback to AI coding assistants, fostering a creative community around pet design and development.

How It Works

Petdex operates through three interconnected components: a public web gallery (petdex.crafter.run) for community interaction, a powerful CLI built with Bun and TypeScript for managing pets, and a desktop application (macOS) that displays pets floating on the user's screen, reacting dynamically to the coding agent's activity. Pets are packaged as simple folders containing a pet.json metadata file and a spritesheet.{webp,png}. These spritesheets, rendered as an 8x9 grid of frames, are mapped to predefined animation states (e.g., idle, wave, run) that the coding agent can trigger, providing visual cues for agent actions. The web stack leverages Next.js 16, React 19, Drizzle with Postgres, and Redis, while the CLI is distributed as a single npm binary.

Quick Start & Requirements

• Browse Pets: Visit petdex.crafter.run.
• Install a Pet: Use the CLI: npx petdex install <slug>.
• Run Desktop App: Execute npx petdex init.
• Development: Local development options include bun run dev:mock (UI focus, no credentials needed), bun run dev:docker (DB/Auth focus, requires Docker), or bun run dev (full setup, maintainers only).
• Prerequisites: Bun, npm, Docker (for certain dev modes), Postgres, Redis (for local dev). The desktop app requires macOS. Authentication is handled via Clerk OAuth.
• Links: Web Gallery & API: petdex.crafter.run, Community: Discord (link available on website).

Highlighted Details

• Real-time animated pets that visually react to coding agent activity.
• A curated "Built with Petdex" catalog showcasing third-party projects leveraging the platform's APIs.
• User-submitted fan art pets, fostering a creative and participatory ecosystem.
• A straightforward CLI for installing pets and submitting new creations.

Maintenance & Community

The project actively encourages community involvement through its Discord server, offering channels for feedback, showcases, and development discussions. Contributions via pull requests are welcomed for bug fixes and feature additions, guided by a CONTRIBUTING.md file. Petdex commits to reviewing IP takedown requests within 48 hours.

Licensing & Compatibility

The source code for Petdex is licensed under the permissive MIT license. Pet assets themselves remain the intellectual property of their respective submitters, who can declare their own licenses. The MIT license generally permits commercial use and integration into closed-source projects.

Limitations & Caveats

The desktop application component appears to be specific to macOS, utilizing Zig and WebKit. As pet assets are user-submitted fan art, intellectual property rights reside with the original creators, necessitating a formal takedown process for rights holders. The project structure indicates ongoing development across its various components.