claude-pet-companion 2.2.0

A 3D virtual pet plugin for Claude Code with 10 evolution stages and 5 paths

Claude Code Pet Companion

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

✨ 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

pip install claude-pet-companion

From Source

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

Windows

Run the installer script:

python install.py

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

---

Uninstallation

Via pip

pip uninstall claude-pet-companion

From Source

python uninstall.py

Uninstall Options

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

{
  "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:

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