Animated pets that live on your screen and react to your coding in real-time
🐾 One command to bring your pet to life 🐾
npm install -g petdex-cc
petdex-cc install bobaHow is this different from
npx petdex install?The original
petdexgives you a basic pet.petdex-ccadds a deep Claude Code integration layer — hooks into your coding workflow, a level progression system, AI-generated speech, time-aware greetings, and interactive effects. Your pet isn't just decoration — it lives in your coding session.
|
🎯 Real-time Reactions Pet changes animation as you read, edit, run commands, complete tasks, or hit errors |
🏆 8-Level Progression Byte → Process → Thread → Module → Kernel → Neural → Quantum → Singularity |
|
🤖 AI Speech Bubbles Context-aware dialogue generated by Claude, or built-in preset lines |
🕐 Time-Aware Greetings Morning, lunch, afternoon, evening, night, and midnight messages in Chinese |
|
🎮 Interactive Drag pet anywhere, right-click menu, rapid-click easter egg |
💾 State Persistence Level and event count survive restarts (HMAC-signed, tamper-resistant) |
- Node.js >= 18
- Claude Code installed
# 1. Browse pets → https://petdex.crafter.run/
# 2. Find one you like, note the slug (e.g. "boba")
# 3. Install globally and set up your pet:
npm install -g petdex-cc
petdex-cc install bobaWhy global install?
petdex-ccregisters a CLI command so you can runpetdex-cc start,petdex-cc stop, etc. from anywhere. Usingnpxworks for one-shot installs but the CLI commands won't be available in new terminal sessions.Auto-start:
petdex-cc installautomatically enables auto-start on login. Usepetdex-cc autostart --disableto turn it off.
| Slug | Name | Description |
|---|---|---|
boba |
🦦 Boba | Tiny otter sipping bubble tea |
doraemon |
🐱 Doraemon | Blue robot-cat from the future |
noir-webling |
🕷️ Noir Webling | Monochrome spider detective |
ikun-hoops |
🏀 IKUN Hoops | Hoodie chick with a basketball |
ddo-zvzo |
😎 ddo-zvzo | Purple mascot with sunglasses |
mochi |
🐱 Mochi | Orange-and-white chibi cat |
Browse all 1,569+ pets at petdex.crafter.run 🎨
🌏 For users in China (国内用户加速)
The first install downloads the Electron binary (~100MB) from GitHub, which can be slow or blocked. Configure npm to use China mirrors before installing:
# Install globally (use official registry to ensure latest version)
npm install -g petdex-cc --registry https://registry.npmjs.org
petdex-cc install boba🔧 Troubleshooting
ERR_MODULE_NOT_FOUND: Cannot find package '@electron/remote'
This was a bug in versions before 0.1.6. Update to the latest version:
npm uninstall -g petdex-cc
npm install -g petdex-cc
petdex-cc install bobaEPERM / EBUSY errors
The pet process is still running and locking files. Stop it first:
# Windows PowerShell
Stop-Process -Name electron -Force -ErrorAction SilentlyContinue
# macOS / Linux
pkill -f electron
# Then reinstall
npm install -g petdex-cc
petdex-cc install bobaECONNRESET / ETIMEDOUT during install
Electron cannot download from GitHub. Set the mirror (see "For users in China" above).
Cannot find module 'auto-launch'
Your npm registry is pointing to a mirror with a cached older version. Install from the official registry:
npm uninstall -g petdex-cc
npm install -g petdex-cc --registry https://registry.npmjs.orgEvery Claude Code action triggers a pet reaction:
| Claude Code Event | Pet Animation | Speech Bubble |
|---|---|---|
| 🟢 Session starts | Waving 👋 | "Let's get to work!" |
| 📖 Reading a file | Review 🔍 | "Reading filename..." |
| ✏️ Editing a file | Idle | "Edited filename" |
| Running 🏃 | "Running command..." | |
| 🔍 Searching (Glob/Grep) | Waiting ⏳ | "Searching..." |
| ❌ Tool fails | Failed 😢 | "Oops, something went wrong" + AI encouragement |
| ✅ Task completes | Jumping 🎉 | "Task complete!" + AI celebration |
| 🛑 Claude stops | Jumping | "Task complete!" (60% AI speech) |
| Failed | Error message + AI comfort | |
| 💤 Idle (10+ min) | Waving | Time-aware Chinese greeting |
| ⬆️ Level up | Current state | "Level up! Kernel!" + all effects activate |
| Action | Effect |
|---|---|
| Drag | Click and drag to move your pet anywhere |
| Right-click | Context menu: Show/Hide, About, Quit |
| System tray | Right-click tray icon for menu |
| Easter egg | Rapidly click for escalating reactions (2→4→6→9→12→15 clicks) |
Your pet levels up based on cumulative Claude Code events:
| Lv | Name | Events | Effect | |
|---|---|---|---|---|
| 1 | Byte | 0 | 🟣 Base pet | |
| 2 | Process | 50 | 🟢 Breathing glow | |
| 3 | Thread | 200 | 🔵 Rotating aura ring | |
| 4 | Module | 500 | 🟣 Enhanced aura | |
| 5 | Kernel | 1,000 | 🟡 Floating light particles | |
| 6 | Neural | 2,000 | 🩷 Particle storm | |
| 7 | Quantum | 5,000 | 🩵 Energy field | |
| 8 | Singularity | 10,000 | 🌟 Golden halo + all effects |
When an Anthropic API key is available (auto-detected from Claude Code settings), your pet generates context-aware speech:
| Scene | Trigger | Example AI Response |
|---|---|---|
task_complete |
Task finishes | "做得好！继续加油！" |
error |
Tool fails | "别担心，bugs难免的~" |
idle |
Idle 10+ minutes | "还在吗？" |
level_up |
Level threshold crossed | "升级啦！太厉害了！" |
- 2-minute cooldown between AI calls (level-ups bypass this)
- 5-second timeout — falls back to preset lines if API is slow
- No API key? Built-in preset lines work great — 7 task, 5 error, 5 idle, 4 level-up lines
petdex-cc install <slug> # Download pet, configure hooks, and launch
petdex-cc start # Start the desktop pet
petdex-cc stop # Gracefully stop the pet
petdex-cc list # Browse all pets from Petdex registry
petdex-cc switch <slug> # Switch pets at runtime (downloads if needed)
petdex-cc status # Show pet name, level, events, running status
petdex-cc update # Update petdex-cc to the latest version
petdex-cc uninstall # Remove hooks, stop pet, delete all data
petdex-cc autostart # View auto-start status
petdex-cc autostart --enable # Enable auto-start on login (enabled by default on install)
petdex-cc autostart --disable # Disable auto-start on login
petdex-cc config [options] # Configure settings⚙️ Config options
petdex-cc config --api-key <key> # Anthropic API key for AI speech
petdex-cc config --api-base-url <url> # API base URL
petdex-cc config --cooldown <minutes> # AI call cooldown (default: 2)API credentials are auto-detected from
~/.claude/settings.json— most users don't need manual config.
┌─────────────────────────────────────────────────┐
│ Claude Code │
│ (tool use, task complete, errors, idle, etc.) │
└──────────┬─────────────────────────┬────────────┘
│ hooks │ statusline
▼ ▼
┌──────────────────┐ ┌───────────────────────┐
│ bridge.ps1/.sh │ │ statusline-bridge.ps1 │
└────────┬─────────┘ └──────────┬────────────┘
│ HTTP POST /event │ HTTP POST /statusline
▼ ▼
┌─────────────────────────────────────────────────┐
│ petdex-cc (Electron) │
│ │
│ ┌──────────────┐ ┌──────────┐ ┌────────────┐ │
│ │ event-mapper │ │ storage │ │ ai-speech │ │
│ │ event → action│ │ level, XP │ │ Claude Haiku│ │
│ └──────┬───────┘ └─────┬────┘ └─────┬──────┘ │
│ │ │ │ │
│ └─────────┬───────┘ │ │
│ ▼ │ │
│ ┌─────────────────┐ │ │
│ │ IPC to window │◀─────────────┘ │
│ └────────┬────────┘ │
└──────────────────┼──────────────────────────────────┘
▼
┌──────────────────┐
│ Pet Window (HTML) │ transparent, always-on-top
│ │
│ ┌─── sprite ───┐ │ 9 animation states
│ │ bubble │ │ 3s / 8s auto-dismiss
│ │ token badge│ │ real-time token counter
│ │ level badge│ │ Lv tag + color
│ │ effects │ │ glow/aura/particles/halo
│ └──────────────┘ │
└──────────────────┘
📁 Project structure
petdex-cc/
├── bin/cli.ts CLI entry point (8 commands)
├── src/
│ ├── main/ Electron main process
│ │ ├── index.ts Window creation, event loop, IPC
│ │ ├── server.ts HTTP server (hooks → pet, port 17321)
│ │ ├── ai-speech.ts AI speech via Anthropic Messages API
│ │ ├── storage.ts HMAC-signed state persistence
│ │ ├── tray.ts System tray with cat-face icon
│ │ └── event-mapper.ts 8 hook events → pet actions
│ ├── renderer/ Electron renderer (pet UI)
│ │ ├── index.html Transparent window + CSS effects
│ │ ├── renderer.ts IPC coordination + level effects
│ │ ├── pet-sprite.ts 9-state spritesheet engine
│ │ ├── bubble.ts Speech bubble system
│ │ ├── click-through.ts Transparent click pass-through
│ │ ├── drag.ts Drag + click easter egg
│ │ └── context-menu.ts Right-click menu
│ ├── cli/ CLI command implementations
│ ├── hooks/ Claude Code hooks (register/unregister)
│ ├── petdex-api/ Petdex registry client
│ └── shared/ Shared types and constants
git clone https://github.com/devnomad-byte/petdex-cc.git
cd petdex-cc
npm install
npm run build
# Run in dev mode
npx electron .
# Install globally for CLI
npm link
petdex-cc install bobaAuto-detected settings
petdex-cc reads these from ~/.claude/settings.json automatically:
| Setting | Used for |
|---|---|
ANTHROPIC_AUTH_TOKEN |
API key for AI speech |
ANTHROPIC_BASE_URL |
API endpoint for AI speech |
Data locations
| Path | Contents |
|---|---|
~/.petdex-cc/pets/<slug>/ |
Downloaded spritesheet + pet.json |
~/.petdex-cc/data/state.json |
Level, events, pet slug (HMAC-signed) |
~/.petdex-cc/data/state.sig |
HMAC-SHA256 signature |
~/.petdex-cc/hooks/ |
Bridge scripts |
~/.petdex-cc/config.json |
User config (API key, cooldown) |
| Hook | Matcher | What triggers it |
|---|---|---|
PostToolUse |
Read|Edit|Write|Bash|Glob|Grep |
After any tool call |
PostToolUseFailure |
— | After a tool call fails |
Stop |
— | Claude finishes a response |
StopFailure |
— | Claude stops with error |
Notification |
idle_prompt |
User is idle |
SessionStart |
startup|resume |
Claude Code launches or resumes |
SessionEnd |
— | Claude Code session ends |
TaskCompleted |
— | A task is marked complete |
Built with 💜 for the Claude Code community
Pets powered by Petdex · 1,569+ community pets and growing