claude-pet-companion 2.1.0

A pixel-art virtual pet plugin for Claude Code

Claude Code Pet Companion v2.0

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

✨ What's New in v2.0

Major visual overhaul with 50+ enhancements:

• 🎨 5 Color Themes - Blue, Pink, Green, Dark, Purple
• 👀 Mouse Eye Tracking - Pet watches your cursor
• 🎭 9 Expressions - Surprised, Excited, Proud, Confused + more
• ✨ Enhanced Particles - Sparkles, notes, code symbols
• 🎊 Level Celebrations - Ring expansion + particle burst
• 🔄 Combo System - Chain actions for bonus XP
• 🐱 Ears & Tail - Animated ears that twitch, swaying tail
• 💨 Breathing Effect - Subtle body scaling animation
• 🎯 Smart Drag - Edge detection + elastic bounce

---

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

Run

claude-pet
# or
pet-companion

From Source

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

---

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.