✨ petdex-cc ✨

Desktop Pet Companion for Claude Code

Animated pets that live on your screen and react to your coding in real-time

🌐 English · 🇨🇳 中文文档

🐾 One command to bring your pet to life 🐾

npm install -g petdex-cc
petdex-cc install boba

🌟 Why petdex-cc?

How is this different from npx petdex install?

The original petdex gives you a basic pet. petdex-cc adds 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)

🚀 Quick Start

Prerequisites

• Node.js >= 18
• Claude Code installed

Install

# 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 boba

Why global install? petdex-cc registers a CLI command so you can run petdex-cc start, petdex-cc stop, etc. from anywhere. Using npx works for one-shot installs but the CLI commands won't be available in new terminal sessions.

Auto-start: petdex-cc install automatically enables auto-start on login. Use petdex-cc autostart --disable to turn it off.

🐾 Popular Pets

Browse all 1,569+ pets at petdex.crafter.run 🎨

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

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 boba

EPERM / 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 boba

ECONNRESET / 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.org

🎬 What Your Pet Does

Every 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 a command | 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) | | ⚠️ Claude errors | Failed | Error message + AI comfort | | 💤 Idle (10+ min) | Waving | Time-aware Chinese greeting | | ⬆️ Level up | Current state | "Level up! Kernel!" + all effects activate |

🎮 Pet Interactions

| 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) |

🏆 Level System

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 |

🤖 AI Speech

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

📋 CLI Reference

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

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.

🏗️ Architecture

 ┌─────────────────────────────────────────────────┐
 │                   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
          │  └──────────────┘ │
          └──────────────────┘

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

🔧 Developer Setup

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 boba

⚙️ Configuration Reference

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 |

| 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) |

🪝 Hooks Reference

| 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 |

⭐ Star History

📄 License

MIT

Built with 💜 for the Claude Code community

Pets powered by Petdex · 1,569+ community pets and growing