petdex-cc 0.1.6 → 0.1.8

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 devnomad-byte
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 devnomad-byte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,44 +1,115 @@
 <div align="center">
 
-# petdex-cc
+<br />
 
-**Desktop Pet Companion for Claude Code**
+# ✨ petdex-cc ✨
 
-*Animated pets that live on your screen and react to your coding in real-time*
+### Desktop Pet Companion for Claude Code
 
-[![npm version](https://img.shields.io/badge/version-0.1.1-8b5cf6?style=flat-square)](https://www.npmjs.com/package/petdex-cc)
-[![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0ea5e9?style=flat-square)]()
-[![node](https://img.shields.io/badge/node-%3E%3D18-22c55e?style=flat-square)]()
-[![license](https://img.shields.io/badge/license-MIT-f59e0b?style=flat-square)]()
-[![pets](https://img.shields.io/badge/pets-1%2C569%20available-ec4899?style=flat-square)](https://petdex.crafter.run)
+**Animated pets that live on your screen and react to your coding in real-time**
 
-[English](./README.md) · [中文文档](./README_CN.md)
+<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>
 
 ---
 
-## What is petdex-cc?
+<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>
+
+---
 
-petdex-cc brings **animated desktop pets** to your Claude Code workflow. Pick any pet from [Petdex](https://petdex.crafter.run/) (1,569+ community pets), install with one command, and your companion appears on your desktop — reading code with you, celebrating completions, cheering you through errors, and growing stronger as you code.
+## 🌟 Why petdex-cc?
 
 > **How is this different from `npx petdex install`?**
-> The original `petdex` command 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.
+>
+> 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%">
 
-### Features at a glance
+🤖 **AI Speech Bubbles**
 
-- **Real-time reactions** — pet changes animation when you read, edit, run commands, complete tasks, or hit errors
-- **8-level progression** — Byte → Process → Thread → Module → Kernel → Neural → Quantum → Singularity, with escalating visual effects
-- **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 your pet anywhere, right-click for menu, rapid-click easter egg
-- **System tray** — show/hide, about, quit from the taskbar
-- **State persistence** — level and event count survive restarts (HMAC-signed, tamper-resistant)
-- **1,569+ pets** — browse [petdex.crafter.run](https://petdex.crafter.run/) and install any community pet
+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
+## 🚀 Quick Start
 
 ### Prerequisites
 
@@ -50,77 +121,171 @@ petdex-cc brings **animated desktop pets** to your Claude Code workflow. Pick an
 ```bash
 # 1. Browse pets → https://petdex.crafter.run/
 # 2. Find one you like, note the slug (e.g. "boba")
-# 3. Install:
+# 3. Install globally and set up your pet:
 
-npx petdex-cc install boba
+npm install -g petdex-cc
+petdex-cc install boba
 ```
 
-Your pet appears on the desktop immediately and starts reacting to Claude Code.
+> **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:
 
-### Popular pets
+```bash
+# Set npm registry to China mirror
+npm config set registry https://registry.npmmirror.com
 
-| 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 |
+# Set Electron download mirror
+npm config set electron_mirror https://npmmirror.com/mirrors/electron/
+
+# Then install globally
+npm install -g petdex-cc
+petdex-cc install boba
+```
+
+These settings are persistent — you only need to run them once.
+
+</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**
 
-> Browse all 1,569+ pets at [**petdex.crafter.run**](https://petdex.crafter.run/)
+Electron cannot download from GitHub. Set the mirror (see "For users in China" above).
+
+</details>
 
 ---
 
-## What Your Pet Does
+## 🎬 What Your Pet Does
 
 Every Claude Code action triggers a pet reaction:
 
-| Claude Code event | Pet animation | Speech bubble |
+| 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
-
-- **Drag** — click and drag to move your pet anywhere
-- **Right-click** — context menu with Show/Hide, About, Quit
-- **System tray** — right-click the tray icon for menu
-- **Easter egg** — rapidly click your pet for escalating reactions (2 → 4 → 6 → 9 → 12 → 15 clicks)
+| 🟢 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
+## 🏆 Level System
 
-Your pet levels up based on cumulative Claude Code events. Each level unlocks new visual effects:
+Your pet levels up based on cumulative Claude Code events:
 
-| Lv | Name | Events | Color | Effect |
+| Lv | Name | Events | | Effect |
 |:---:|---|---:|---|---|
-| 1 | **Byte** | 0 | Silver | Base pet |
-| 2 | **Process** | 50 | Green | Breathing glow |
-| 3 | **Thread** | 200 | Blue | Rotating aura ring |
-| 4 | **Module** | 500 | Purple | Enhanced aura |
-| 5 | **Kernel** | 1,000 | Amber | Floating light particles |
-| 6 | **Neural** | 2,000 | Pink | Particle storm |
-| 7 | **Quantum** | 5,000 | Cyan | Energy field |
-| 8 | **Singularity** | 10,000 | Gold | Golden halo + all effects |
+| 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
+## 🤖 AI Speech
 
-When an Anthropic API key is available (auto-detected from Claude Code settings or set via `petdex-cc config`), your pet generates **context-aware 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 |
+| Scene | Trigger | Example AI Response |
 |---|---|---|
 | `task_complete` | Task finishes | "做得好！继续加油！" |
 | `error` | Tool fails | "别担心，bugs难免的~" |
@@ -129,11 +294,11 @@ When an Anthropic API key is available (auto-detected from Claude Code settings
 
 - **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 lines, 5 error lines, 5 idle lines, 4 level-up lines
+- **No API key?** Built-in preset lines work great — 7 task, 5 error, 5 idle, 4 level-up lines
 
 ---
 
-## CLI Reference
+## 📋 CLI Reference
 
 ```bash
 petdex-cc install <slug>    # Download pet, configure hooks, and launch
@@ -143,10 +308,16 @@ 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 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
+<details>
+<summary>⚙️ Config options</summary>
+
+<br />
 
 ```bash
 petdex-cc config --api-key <key>             # Anthropic API key for AI speech
@@ -156,9 +327,11 @@ 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
+## 🏗️ Architecture
 
 ```
  ┌─────────────────────────────────────────────────┐
@@ -198,25 +371,10 @@ petdex-cc config --cooldown <minutes>         # AI call cooldown (default: 2)
           └──────────────────┘
 ```
 
----
-
-## 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 .
+<details>
+<summary>📁 Project structure</summary>
 
-# Install globally for CLI
-npm link
-petdex-cc install boba
-```
-
-### Project structure
+<br />
 
 ```
 petdex-cc/
@@ -239,21 +397,38 @@ petdex-cc/
 │   │   └── context-menu.ts   Right-click menu
 │   ├── cli/                  CLI command implementations
 │   ├── hooks/                Claude Code hooks (register/unregister)
-│   │   ├── register.ts       Writes to ~/.claude/settings.json
-│   │   ├── write-scripts.ts  Cross-platform bridge scripts
-│   │   ├── bridge.ps1        Windows PowerShell bridge
-│   │   └── bridge.sh         Unix bash bridge
 │   ├── petdex-api/           Petdex registry client
-│   │   ├── client.ts         Manifest fetch + slug lookup
-│   │   └── download.ts       Streaming download with progress
 │   └── shared/               Shared types and constants
 ```
 
+</details>
+
 ---
 
-## Configuration Reference
+## 🔧 Developer Setup
 
-### Auto-detected settings
+```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:
 
@@ -262,15 +437,12 @@ petdex-cc reads these from `~/.claude/settings.json` automatically:
 | `ANTHROPIC_AUTH_TOKEN` | API key for AI speech |
 | `ANTHROPIC_BASE_URL` | API endpoint for AI speech |
 
-### Manual config
+</details>
 
-Stored in `~/.petdex-cc/config.json`:
+<details>
+<summary>Data locations</summary>
 
-```bash
-petdex-cc config --api-key <key> --api-base-url <url> --cooldown 2
-```
-
-### Data locations
+<br />
 
 | Path | Contents |
 |---|---|
@@ -280,11 +452,11 @@ petdex-cc config --api-key <key> --api-base-url <url> --cooldown 2
 | `~/.petdex-cc/hooks/` | Bridge scripts |
 | `~/.petdex-cc/config.json` | User config (API key, cooldown) |
 
----
+</details>
 
-## Hooks Reference
+---
 
-petdex-cc registers these hooks in `~/.claude/settings.json`:
+## 🪝 Hooks Reference
 
 | Hook | Matcher | What triggers it |
 |---|---|---|
@@ -299,13 +471,28 @@ petdex-cc registers these hooks in `~/.claude/settings.json`:
 
 ---
 
-## License
+<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 align="center">
-  <sub>Built for the <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a> community</sub><br />
-  <sub>Pets powered by <a href="https://petdex.crafter.run/">Petdex</a></sub>
 </div>