<div align="center">

<br />

# ✨ petdex-cc ✨

### Desktop Pet Companion for Claude Code

**Animated pets that live on your screen and react to your coding in real-time**

<br />

[![npm version](https://img.shields.io/npm/v/petdex-cc?style=for-the-badge&color=8b5cf6&labelColor=1a1a2e)](https://www.npmjs.com/package/petdex-cc)
[![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0ea5e9?style=for-the-badge&labelColor=1a1a2e)]()
[![node](https://img.shields.io/badge/node-%3E%3D18-22c55e?style=for-the-badge&labelColor=1a1a2e)]()
[![license](https://img.shields.io/badge/license-MIT-f59e0b?style=for-the-badge&labelColor=1a1a2e)](./LICENSE)
[![pets](https://img.shields.io/badge/pets-1%2C569%20available-ec4899?style=for-the-badge&labelColor=1a1a2e)](https://petdex.crafter.run)
[![GitHub stars](https://img.shields.io/github/stars/devnomad-byte/petdex-cc?style=for-the-badge&color=f59e0b&labelColor=1a1a2e)](https://github.com/devnomad-byte/petdex-cc/stargazers)

<br />

[🌐 English](./README.md) · [🇨🇳 中文文档](./README_CN.md)

</div>

---

<div align="center">

<img src="./boba.gif" alt="petdex-cc demo" width="600" />

</div>

---

<div align="center">

🐾 **One command to bring your pet to life** 🐾

</div>

```bash
npm install -g petdex-cc
petdex-cc install boba
```

<div align="center">
<i>全局安装后，宠物出现在桌面上，开始实时响应你的 Claude Code 操作 🎉</i>
</div>

---

## 🌟 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.

<table>
<tr>
<td width="50%">

🎯 **Real-time Reactions**

Pet changes animation as you read, edit, run commands, complete tasks, or hit errors

</td>
<td width="50%">

🏆 **8-Level Progression**

Byte → Process → Thread → Module → Kernel → Neural → Quantum → Singularity

</td>
</tr>
<tr>
<td width="50%">

🤖 **AI Speech Bubbles**

Context-aware dialogue generated by Claude, or built-in preset lines

</td>
<td width="50%">

🕐 **Time-Aware Greetings**

Morning, lunch, afternoon, evening, night, and midnight messages in Chinese

</td>
</tr>
<tr>
<td width="50%">

🎮 **Interactive**

Drag pet anywhere, right-click menu, rapid-click easter egg

</td>
<td width="50%">

💾 **State Persistence**

Level and event count survive restarts (HMAC-signed, tamper-resistant)

</td>
</tr>
</table>

---

## 🚀 Quick Start

### Prerequisites

- [Node.js](https://nodejs.org/) >= 18
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed

### Install

```bash
# 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

<table>
<tr>
<th>Slug</th>
<th>Name</th>
<th>Description</th>
</tr>
<tr>
<td><code>boba</code></td>
<td>🦦 Boba</td>
<td>Tiny otter sipping bubble tea</td>
</tr>
<tr>
<td><code>doraemon</code></td>
<td>🐱 Doraemon</td>
<td>Blue robot-cat from the future</td>
</tr>
<tr>
<td><code>noir-webling</code></td>
<td>🕷️ Noir Webling</td>
<td>Monochrome spider detective</td>
</tr>
<tr>
<td><code>ikun-hoops</code></td>
<td>🏀 IKUN Hoops</td>
<td>Hoodie chick with a basketball</td>
</tr>
<tr>
<td><code>ddo-zvzo</code></td>
<td>😎 ddo-zvzo</td>
<td>Purple mascot with sunglasses</td>
</tr>
<tr>
<td><code>mochi</code></td>
<td>🐱 Mochi</td>
<td>Orange-and-white chibi cat</td>
</tr>
</table>

> Browse all 1,569+ pets at [**petdex.crafter.run**](https://petdex.crafter.run/) 🎨

<details>
<summary>🌏 For users in China (国内用户加速)</summary>

<br />

The first install downloads the Electron binary (~100MB) from GitHub, which can be slow or blocked. Configure npm to use China mirrors before installing:

```bash
# Install globally (use official registry to ensure latest version)
npm install -g petdex-cc --registry https://registry.npmjs.org
petdex-cc install boba
```

</details>

<details>
<summary>🔧 Troubleshooting</summary>

<br />

**`ERR_MODULE_NOT_FOUND: Cannot find package '@electron/remote'`**

This was a bug in versions before 0.1.6. Update to the latest version:

```bash
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:

```bash
# 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:

```bash
npm uninstall -g petdex-cc
npm install -g petdex-cc --registry https://registry.npmjs.org
```

</details>

---

## 🎬 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

```bash
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
```

<details>
<summary>⚙️ Config options</summary>

<br />

```bash
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.

</details>

---

## 🏗️ 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
          │  └──────────────┘ │
          └──────────────────┘
```

<details>
<summary>📁 Project structure</summary>

<br />

```
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
```

</details>

---

## 🔧 Developer Setup

```bash
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

<details>
<summary>Auto-detected settings</summary>

<br />

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 |

</details>

<details>
<summary>Data locations</summary>

<br />

| 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) |

</details>

---

## 🪝 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 |

---

<div align="center">

## ⭐ Star History

<a href="https://www.star-history.com/?repos=devnomad-byte%2Fpetdex-cc&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=devnomad-byte/petdex-cc&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=devnomad-byte/petdex-cc&type=date&legend=top-left" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=devnomad-byte/petdex-cc&type=date&legend=top-left" />
 </picture>
</a>

<br />

## 📄 License

[MIT](./LICENSE)

<br />

Built with 💜 for the [Claude Code](https://docs.anthropic.com/en/docs/claude-code) community

Pets powered by [**Petdex**](https://petdex.crafter.run/) · 1,569+ community pets and growing

</div>
🎯 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)
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