Petdex: animierte Begleiter für Coding-Agenten aus Galerie, CLI und Desktop-App
Die öffentliche Galerie animierter Haustiere für Codex, Claude Code, OpenCode und Gemini CLI.
Auf einen Blick
- Was ist das?
- crafter-station/petdex betreibt unter petdex.dev eine öffentliche Galerie animierter Pets, die auf Aktivitäten von Coding-Agenten reagieren. Wie das Paketformat aussieht, wie die Installation mit einem Befehl läuft und wie Builder die HTTP-API nutzen.
- Für wen ist es gedacht?
- Petdex ist eine Spielerei mit Substanz: Jedes Pet besteht aus pet.json und einem Spritesheet im 8x9- oder v2 8x11-Raster, installiert wird es mit npx petdex install boba nach ~/.petdex/pets/boba/, und die Desktop-App von petdex.dev/download lässt es auf jedem Toolaufruf des Agenten animieren.
- Darf ich es kommerziell nutzen?
- Ja. MIT ist eine freizügige Lizenz: Sie dürfen darauf aufbauende Software nutzen, verändern und verkaufen, solange Sie die Urheberrechts- und Lizenzhinweise beibehalten.
- Wird es noch gepflegt?
- Ja. Die letzten Commits kamen vor 1 Tag.
- In welcher Sprache ist es geschrieben?
- Hauptsächlich TypeScript, laut der Sprachstatistik von GitHub.
Die Antworten beruhen auf den GitHub-Daten des Projekts (zuletzt abgeglichen am 14. September 2026) und auf unserer Analyse. Sie sind keine Rechtsberatung.
TIEFGEHENDE OPEN-SOURCE-ANALYSE
Galerie, CLI und Desktop-App: drei Teile, ein Format
Petdex besteht laut README aus drei Teilen, die zusammenarbeiten. Eine Webgalerie unter petdex.dev, in der die Community animierte Pets im Codex-Spriteformat einreicht, prüft und zeigt; eine CLI, die jedes Pet mit einem Befehl auf die eigene Maschine bringt und es direkt an Codex ausliefert; und eine Desktop-App, die ein Pet über den Bildschirm schweben lässt und in Echtzeit auf die Aktivität des Coding-Agenten reagiert. Die Formel des Projekts liest sich knapp: Jedes Pet ist ein Ordner, jeder Ordner ein Galerieeintrag, jeder Eintrag ist ein npx petdex install entfernt. Die Metadaten weisen 3.987 Sterne, 191 Forks und 26 offene Issues aus; die Sprache ist TypeScript, lizenziert ist der Code unter MIT. Hinter dem Projekt steht Crafter Station, als Lead wird @RaillyHugo genannt.
Das Pet-Paketformat: pet.json und das Spritesheet-Raster
Der technische Kern ist absichtlich klein: Ein Pet besteht aus zwei Dateien. pet.json trägt die Metadaten, also Name, Slug, Tags, Vibes, Typ, Framegröße und Animationszustände; daneben liegt das Spritesheet als webp oder png, gerendert als 8x9-Raster von 192x208-Pixel-Frames oder als v2 8x11-Raster. Der native Renderer versteht neun Zustandszeilen: idle, running-right, running-left, waving, jumping, failed, waiting, running und review. Codex und die unterstützten Coding-Agenten mappen ihre Aktivitäts-Hooks auf diese Zustände, sodass das Pet nicht dekorativ animiert, sondern die Arbeitsphase des Agenten spiegelt: ein Sprung bei Erfolg, eine bestimmte Zeile beim Warten. Das v2 8x11-Atlasformat lässt zusätzlich zwei Zeilen frei, die der jeweilige Client selbst belegen kann. Diese Schlichtheit erklärt, warum die Galerie wachsen kann: Ein Beitrag ist ein Ordner mit zwei Dateien, keine Build-Pipeline.
Von npx petdex install boba bis zur schwebenden Desktop-App
Die Schnellstart-Checkliste des README führt in drei Schritten zum sichtbaren Pet. Zuerst installiert npx petdex install boba ein bekanntes Pet; danach sollten ~/.petdex/pets/boba/ mit pet.json und einem Spritesheet existieren. Zweitens kommt die Desktop-App von petdex.dev/download, die laut README auf macOS, Linux und Windows läuft. Drittens öffnet man die App, drückt Cmd+, über dem Pet für die Einstellungen, wählt das Pet unter Pets und verbindet die Coding-Agenten unter Agents mit je einem Klick, ganz ohne Terminal. Von da an schwebt das Pet über dem Arbeitsbereich und animiert bei jedem Toolaufruf des Agenten. Die Release-Historie zeigt zwei parallele Linien: petdex-desktop v0.8.0 und v0.7.0 vom 13. und 14. August 2026 sowie die CLI in Version v1.2.2, jeweils frisch gepflegt.
Bauen auf Petdex: die HTTP-API und 21 abgeleitete Projekte
Für Builder definiert das README zwei stabile Oberflächen. Die HTTP-API unter petdex.dev/api/manifest liefert jedes genehmigte Pet mit Slug, Spritesheet-URL, Animationszuständen und Metadaten zurück. Daneben steht das oben beschriebene Pet-Paketformat als offene Spezifikation. Diese Kombination hat bereits 21 quelloffene und source-available Projekte angezogen, die darauf aufbauen, von einem Desktop-Client bis zum Wearable; das Verzeichnis listet petdex.dev/built-with, eigene Projekte werden über ein Issue-Template mit built-with.yml eingereicht. Für die eigene Projekt-Webseite nennt das README den Stack: Next.js 16, React 19, Tailwind, Drizzle mit Postgres, Redis, Clerk und R2. Die CLI ist mit Bun und TypeScript gebaut und wird als einzelne npm-Binärdatei ausgeliefert, die Authentifizierung läuft über Clerk-OAuth mit PKCE.
Der native Desktop-Kern mit Zig-Hookserver auf Port 7777
Ein Detail der Desktop-App springt ins Auge: Laut Architekturabschnitt handelt es sich um eine native SDK-Anwendung mit einem in-prozess laufenden Zig-Hookserver auf 127.0.0.1:7777; der aktuelle Release-Pfad kommt ohne WebView und ohne Node-Sidecar aus. Das ist eine bewusste Entscheidung gegen die übliche Electron-Bauweise und erklärt die Reaktionsfähigkeit der Animation bei Toolaufrufen. Wer selbst an Petdex entwickeln möchte, hat zwei dokumentierte Wege: bun run dev:docker startet den lokalen Vollstack mit Docker oder Podman und etwa 30 Sekunden Aufwärmzeit, während bun run dev gegen echte Dienste läuft und ausgefüllte .env.local-Werte voraussetzt, wofür nur Maintainer zugelassen sind. Der Weg beginnt mit git clone https://github.com/crafter-station/petdex.git, dann bun install, dann bun run dev:docker, und die Site erscheint auf localhost:3000; die ausführliche Anleitung liegt in CONTRIBUTING.md.
Rechte an Pet-Assets, Takedowns und Community-Kanäle
Bei Nutzereinreichungen mit fremden Figuren regelt das README die Rechtslage ausdrücklich: Pets sind eingereichte Fan-Art, Petdex beansprucht keine Rechte am zugrunde liegenden IP. Rechteinhaber können über ein Takedown-Template im Issue-Tracker die Entfernung fordern, mit zugesagter Prüfung innerhalb von 48 Stunden. Die Lizenz ist zweigeteilt: Der Quellcode steht unter MIT, die Pet-Assets bleiben Eigentum der Einreicher unter der Lizenz, die sie selbst erklären. Die Community lebt im Discord mit Kanälen für laufende Arbeit unter #wip und #ship-or-sink, Feedback unter #cli-feedback und Vorstellungen unter #showcase. Einreichungen laufen über petdex.dev/submit oder npx petdex submit ./my-pet/, und die CLI-Referenz liegt vollständig in packages/petdex-cli/README.md.
Fazit: ein niedrigschwelliges Ökosystem um Agenten-Visualisierung
Petdex verbindet einen spielerischen Zweck, ein sichtbares Pet neben dem Code, mit einem erstaunlich sauberen technischen Fundament: einem zweidateigen Paketformat, neun dokumentierten Zustandszeilen, einer manifestbasierten HTTP-API und einer nativen Desktop-App mit Zig-Hookserver statt WebView. Für Einzelnutzer ist der Aufwand minimal, ein npx-Befehl und ein Download von petdex.dev/download genügen, um die Animation über dem Editor zum Laufen zu bringen. Für Builder bietet die 21 Projekte umfassende Built-with-Liste Anhaltspunkte, was sich aus Slugs, Spritesheet-URLs und Metadaten bereits bauen lässt. Wer den Wert solcher Visualisierung anzweifelt, wird nicht überzeugt; wer aber Agentenworkflows beobachtbar machen will, findet hier ein Format, das genau dafür entworfen wurde und dessen Galerie unter petdex.dev jeden Einreichungsstand transparent zeigt.
Redaktionelles Fazit
Petdex ist eine Spielerei mit Substanz: Jedes Pet besteht aus pet.json und einem Spritesheet im 8x9- oder v2 8x11-Raster, installiert wird es mit npx petdex install boba nach ~/.petdex/pets/boba/, und die Desktop-App von petdex.dev/download lässt es auf jedem Toolaufruf des Agenten animieren. Wer eigene Pets bauen will, nutzt die neun Zustandszeilen des Renderers oder die HTTP-API unter petdex.dev/api/manifest; der Quellcode unter crafter-station/petdex ist MIT-lizenziert, die Rechte an den Pet-Assets bleiben bei den Einreichern.
Community-Notizen