Metadata-Version: 2.4
Name: claude-pet-companion
Version: 2.2.0
Summary: A 3D virtual pet plugin for Claude Code with 10 evolution stages and 5 paths
Home-page: https://github.com/anthropics/claude-pet-companion
Author: Claude Code Community
Author-email: noreply@example.com
License: MIT
Project-URL: Homepage, https://github.com/anthropics/claude-pet-companion
Project-URL: Documentation, https://github.com/anthropics/claude-pet-companion/blob/main/README.md
Project-URL: Repository, https://github.com/anthropics/claude-pet-companion
Project-URL: Issues, https://github.com/anthropics/claude-pet-companion/issues
Keywords: claude-code,plugin,pet,companion,pixel-art,gamification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author-email
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Claude Code Pet Companion

A beautiful animated desktop pet that lives on your screen while you code with Claude Code.

![Version](https://img.shields.io/badge/version-2.2.0-blue)
![Python](https://img.shields.io/badge/python-3.8+-green)
![License](https://img.shields.io/badge/license-MIT-green)

## ✨ What's New in v2.2

**3D Evolution System:**
- 🎮 **10 Evolution Stages** - From Egg to Ancient with unique visual appearances
- 🌟 **5 Evolution Paths** - Coder, Warrior, Social, Night Owl, Balanced
- 🎨 **3D Pseudo-Rendering** - Multi-layer depth simulation with dynamic lighting
- 📦 **Evolution Items** - Collect special items to trigger evolutions
- ⚔️ **100+ Accessories** - Path-specific items unlocked at each stage
- 🌙 **Time-Based Lighting** - Dynamic ambient lighting that changes throughout the day

---

## ✨ What's New in v2.1

**Productivity & Workflow Enhancement:**
- 📊 **Real-time Productivity Score** - Track your coding efficiency (0-100)
- 🧠 **Focus Time Monitoring** - Detect flow states automatically
- 🔥 **Combo System** - Chain actions for bonus XP rewards
- ☕ **Smart Break Reminders** - Health-conscious 50-minute work alerts
- ⚡ **Inline Commands** - /pet-status, /pet-stats directly in Claude Code
- 📈 **Productivity Dashboard** - Standalone stats viewer
- ⏰ **Peak Hour Analysis** - Learn your most productive time
- 💻 **Language Tracking** - See which languages you use most

---

## Features

### 🎮 3D Evolution System (NEW!)

**10 Evolution Stages:**

| Stage | Level | Name | Description |
|-------|-------|------|-------------|
| 0 | 0 | Egg | The beginning - a pulsing egg waiting to hatch |
| 1 | 1 | Hatchling | Breaking free - tiny head peeking from cracked shell |
| 2 | 4 | Baby | Small and round - learning to wobble around |
| 3 | 8 | Child | Growing up - ears perked up, discovering the world |
| 4 | 13 | Pre-Teen | Getting taller - antenna begins to glow |
| 5 | 19 | Teen | Lanky form - personality starts to show |
| 6 | 26 | Young Adult | Mature look - path-specific accessories appear |
| 7 | 36 | Adult | Full power - halo effects and energy particles |
| 8 | 51 | Elder | Wise appearance - mane/beard and wisdom aura |
| 9 | 71 | Ancient | Transcendent form - semi-transparent with orbiting stars |

**5 Evolution Paths:**

| Path | Style | Colors | Special Features |
|------|-------|--------|------------------|
| **Coder** | Tech | Blue/Green | Pixel eyes, binary particles, keyboard cape |
| **Warrior** | Battle | Orange/Red | Sharp eyes, flame aura, sword antenna |
| **Social** | Cute | Pink/Heart | Round body, heart particles, ribbon cape |
| **Night Owl** | Mystery | Purple/Yellow | Glowing eyes, stardust trail, moon charm |
| **Balanced** | Harmony | Green/Teal | Gentle eyes, nature aura, balanced stats |

**Evolution Items:**

| Item | Use | How to Get |
|------|-----|------------|
| 🔹 Code Fragment | Stages 1-3 | Create 5 files |
| ⚔️ Bug Slayer | Stages 4-6 | Fix 10 errors |
| 💎 Wisdom Crystal | Stages 7-8 | 90%+ productivity |
| 🏺 Ancient Relic | Stage 9 | All achievements |
| 🎖️ Friendship Badge | Social boost | 50 interactions |
| 🌙 Moonstone | Night Owl boost | 10hrs night coding |

### 🎨 Theme System

Switch between 5 beautiful color schemes via right-click menu:

| Theme | Description |
|-------|-------------|
| **Blue (Default)** | Classic Claude blue tones |
| **Pink** | Warm rose and magenta |
| **Green** | Fresh nature greens |
| **Dark** | Sleek monochrome |
| **Purple** | Mystical violet vibes |

### 📊 Productivity Tracking

The pet monitors your Claude Code activity in real-time:

| Metric | Description |
|--------|-------------|
| **Productivity Score** | Based on success rate and activity frequency |
| **Focus Score** | Measures continuous work time vs breaks |
| **Combo/Streak** | Bonus XP for rapid consecutive actions |
| **Flow State** | Special effects when focus ≥ 80% |

### 🎭 Dynamic Expressions

| State | Expression |
|-------|-----------|
| Idle | 😊 Happy with smile |
| Thinking | 🤔 Eyes shift with question mark |
| Working | ⚡ Focused with sweat drop |
| Error | 😵 X eyes with worry |
| Success | ✨ Sparkling star eyes |
| Surprised | 😲 Wide eyes, open mouth |
| Excited | 🎉 Shining eyes with sparkles |
| Proud | 😏 Confident smirk |
| Confused | 🤷 Uneven eyes, question mark |

### 🎪 Particle Effects

- **Hearts (♥)** - Love and interaction
- **Stars (★)** - Success and celebration
- **Sparkles (✦)** - Special moments
- **Notes (♪)** - Musical feedback
- **Circles (●)** - Visual pops
- **Code ({} )** - Programming actions
- **Plus (+)** - XP gains

### 💬 Inline Commands (NEW)

Use directly in Claude Code conversation:

```
/pet-status    # Show detailed pet status
/pet-stats     # Show productivity statistics
/pet-focus     # Toggle focus mode
/pet-break     # Enter break mode
/pet-feed      # Feed the pet
/pet-play      # Play with pet
```

---

## Features

### 🎨 Theme System

Switch between 5 beautiful color schemes via right-click menu:

| Theme | Description |
|-------|-------------|
| **Blue (Default)** | Classic Claude blue tones |
| **Pink** | Warm rose and magenta |
| **Green** | Fresh nature greens |
| **Dark** | Sleek monochrome |
| **Purple** | Mystical violet vibes |

### 👁️ Mouse Eye Tracking

The pet's eyes follow your mouse cursor, creating an engaging interactive experience.

### 🎭 Dynamic Expressions

| State | Expression |
|-------|-----------|
| Idle | 😊 Happy with smile |
| Thinking | 🤔 Eyes shift with question mark |
| Working | ⚡ Focused with sweat drop |
| Error | 😵 X eyes with worry |
| Success | ✨ Sparkling star eyes |
| Surprised | 😲 Wide eyes, open mouth |
| Excited | 🎉 Shining eyes with sparkles |
| Proud | 😏 Confident smirk |
| Confused | 🤷 Uneven eyes, question mark |

### 🎪 Particle Effects

- **Hearts (♥)** - Love and interaction
- **Stars (★)** - Success and celebration
- **Sparkles (✦)** - Special moments
- **Notes (♪)** - Musical feedback
- **Circles (●)** - Visual pops
- **Code ({} )** - Programming actions
- **Plus (+)** - XP gains

### 🎮 Interactions

| Action | Effect |
|--------|--------|
| **Drag** | Move pet (with edge protection) |
| **Double-click** | Pet jumps + hearts |
| **Right-click** | Full menu |
| **Hover** | Show controls |

### 📊 Gamification

- **XP System** - Gain experience from coding
- **Leveling** - Progress through levels with celebrations
- **Combo Multiplier** - Chain actions for bonus XP
- **Visual Feedback** - Floating XP numbers

---

## Installation

### Via pip

```bash
pip install claude-pet-companion
```

### From Source

```bash
git clone https://github.com/your-repo/claude-pet-companion.git
cd claude-pet-companion
python install.py
```

### Windows

Run the installer script:
```bash
python install.py
```

Or use the provided batch file: `安装宠物.bat`

---

## Uninstallation

### Via pip

```bash
pip uninstall claude-pet-companion
```

### From Source

```bash
python uninstall.py
```

### Uninstall Options

```bash
# Uninstall plugin only (preserves save data)
python uninstall.py

# Completely uninstall (removes all data)
python uninstall.py --all

# Also remove pip package
python uninstall.py --pip
```

### Windows

Use the provided batch file: `卸载宠物.bat`

Options:
1. Uninstall plugin only (preserves saves)
2. Complete uninstall (deletes all data)
3. Cancel

---

## Configuration

### Theme Selection

Right-click pet → 🎨 **Theme** → Select theme

### Config File

Edit `~/.claude-pet-companion/config.json`:

```json
{
  "theme": "pink",
  "animation_speed": 1.0,
  "float_amplitude": 3.0,
  "pet_name": "Buddy",
  "target_fps": 40,
  "hunger_decay": 0.5,
  "happiness_decay": 0.3
}
```

### Settings

| Setting | Default | Description |
|---------|---------|-------------|
| `theme` | "default" | Color theme name |
| `animation_speed` | 1.0 | Animation multiplier |
| `float_amplitude` | 3.0 | Floating movement range |
| `pet_name` | "Claude" | Pet's name |
| `target_fps` | 40 | Target frame rate |
| `hunger_decay` | 0.5 | Hunger loss per second |
| `happiness_decay` | 0.3 | Happiness loss per second |

---

## Claude Code Integration

The pet automatically responds to your coding activities:

| Activity | XP | Pet Reaction |
|----------|-----|--------------|
| Write file | +15 | Excited + stars |
| Edit file | +10 | Happy + sparkles |
| Run command | +5 | Focused |
| Error detected | - | Worried |
| Chain actions | +Bonus | Combo multiplier! |

---

## Visual Effects

### Background

- **50-step gradient** - Smooth color transition
- **20 twinkling stars** - Animated night sky
- **Glowing grid** - Subtle tech aesthetic
- **Frosted glass bar** - Status panel blur

### Pet Animations

- **Floating** - Gentle bobbing motion
- **Breathing** - Subtle scale pulsing
- **Ear twitching** - Random ear movements
- **Tail swaying** - Sinusoidal tail motion
- **Shadow changes** - Dynamic with floating

### UI Feedback

- **Status bar colors**:
  - 🟢 Green (≥60%) - Healthy
  - 🟡 Yellow (30-60%) - Warning
  - 🔴 Red (<30%) - Critical

---

## Data Storage

```
~/.claude-pet-companion/
├── config.json              # User settings
├── pet_state.json           # Pet stats & level
├── activity.json            # Real-time activity
└── pet_window_state.json    # Window position
```

---

## Controls

### Right-Click Menu

```
🍖 Feed        - Restore hunger (+30)
🎾 Play        - Increase happiness (+25)
❤️ Interact    - Quick happiness (+10)
───────────────
😴 Sleep/Wake  - Toggle sleep mode
📊 Status      - View detailed stats
🎨 Theme       - Change colors
───────────────
❌ Exit        - Close pet
```

### Mouse Actions

- **Single click** - Select/focus
- **Double click** - Jump celebration
- **Right click** - Open menu
- **Drag** - Reposition
- **Scroll wheel** - (Reserved for future)

---

## Development

### Project Structure

```
claude-pet-companion/
├── claude_pet_companion/
│   ├── __init__.py
│   ├── claude_pet_hd.py   # Main pet with animations
│   ├── cli.py             # Entry point
│   ├── config.py          # Configuration system
│   └── themes.py          # Theme definitions
├── scripts/               # Hook scripts
├── skills/                # Claude Code skills
├── data/                  # Default data
└── hooks/                 # Hook definitions
```

### Adding Custom Themes

Edit `claude_pet_companion/themes.py`:

```python
'custom': ColorScheme(
    bg_top='#1a1a2e',
    bg_bottom='#16213e',
    pet_primary='#e94560',
    # ... more colors
)
```

---

## Changelog

### v2.1.0 (2024) - Productivity & Workflow Update
- **Added:** Real-time productivity score tracking
- **Added:** Focus time monitoring and flow state detection
- **Added:** 50-minute work break reminders (health-focused)
- **Added:** Work streak/combo system with bonus XP
- **Added:** Productivity dashboard (`/pet-stats` command)
- **Added:** Peak performance hour analysis
- **Added:** Language usage tracking
- **Enhanced:** Session statistics with summary
- **Enhanced:** Pet status panel with more info
- **Improved:** Claude Code integration hooks

### v2.0.2 (2024-02)
- **Updated:** README with full feature documentation
- **Improved:** Project description on PyPI

### v2.0.1 (2024-02)
- **Added:** Theme system with 5 color schemes
- **Added:** Configuration file support
- **Added:** Mouse eye tracking
- **Added:** 4 new expressions (surprised, excited, proud, confused)
- **Added:** Floating XP numbers
- **Added:** Level-up celebration animation
- **Added:** Combo system for chained actions
- **Added:** Smart edge detection for dragging
- **Added:** Elastic drag with bounce effect
- **Added:** Animated ears and tail
- **Added:** Breathing animation
- **Enhanced:** Particle system with 5 new types
- **Enhanced:** Background with twinkling stars
- **Improved:** Status bar color thresholds

### v2.0.0
- **New:** High-resolution compact UI (240x280)
- **New:** Real-time Claude Code integration
- **New:** Dynamic expressions based on activity
- **New:** XP and leveling system

---

## Requirements

- Python 3.8+
- tkinter (usually included with Python)

---

## License

MIT License - see LICENSE file for details

---

## Credits

Made with ❤️ for the Claude Code community

Contributors welcome! Feel free to open issues and PRs.
