claude-pet-companion 1.0.1

A pixel-art virtual pet plugin for Claude Code

Claude Code Pet Companion

A pixel-art virtual pet plugin for Claude Code that makes programming more fun! Your pet lives in your editor, watches you code, and evolves as you progress.

Features

• Pixel Art Pet: A cute 64x64 pixel pet that animates and reacts to your coding
• Emotional Intelligence: Pet mood changes based on your coding success/failure
• XP & Leveling: Gain XP as you code, level up, and unlock new abilities
• Evolution System: Pet evolves through 7 stages (Egg → Baby → Child → Teen → Adult → Elder → Ancient)
• Achievements: Unlock achievements for coding milestones
• Interactive Care: Feed, play with, and put your pet to sleep
• Draggable UI: Move your pet anywhere on your screen

Quick Start

1. Install the Plugin

   claude --plugin-dir /path/to/claude-pet-companion
   

2. Meet Your Pet

   /pet:status
   

3. Start Coding! Your pet gains XP automatically as you write code, edit files, and run commands.

Commands

Command	Description
/pet:status	View your pet's stats and progress
/pet:feed	Feed your pet (bonus during meal hours!)
/pet:play	Play with your pet to increase happiness
/pet:sleep	Toggle sleep mode to restore energy

How It Works

Activity Tracking

The pet monitors your coding activity through Claude Code hooks:

Activity	XP	Effects
Write file	+10	Happiness +2
Edit file	+10	Happiness +2
Bash success	+5	Happiness +1
Fix error	+25	Special bonus!
Session complete	+50	Happiness +15

Care System

Your pet has three core stats that decay over time:

• Hunger 🍖 - Feed your pet to restore
• Happiness 😊 - Play to keep your pet happy
• Energy ⚡ - Sleep to restore energy

Meal Time Bonuses

Feed during these hours for bonus XP:

• Breakfast: 7-9 AM (+15 hunger, +20 XP)
• Lunch: 12-2 PM (+15 hunger, +20 XP)
• Dinner: 6-8 PM (+15 hunger, +20 XP)

Evolution Path

Level	Stage	Size	New Abilities
1	Egg	32x32	-
10	Child	64x64	Particle effects
20	Teen	80x80	Speech bubbles
30	Adult	96x96	Double XP weekends
50	Elder	128x128	Custom accessories
75	Ancient	160x160	Legendary aura

Project Structure

claude-pet-companion/
├── .claude-plugin/
│   └── plugin.json           # Plugin manifest
├── skills/
│   ├── pet-core/             # Core pet management
│   ├── emotion-tracker/      # Activity & emotion tracking
│   └── pet-commands/         # User commands
├── agents/
│   └── pet-companion.md      # Pet personality
├── hooks/
│   └── hooks.json            # Event tracking hooks
├── webview/
│   ├── index.html            # Pet UI
│   ├── css/                  # Pixel art styles
│   ├── js/                   # Rendering & interaction
│   └── assets/sprites/       # Pixel art sprites
├── scripts/
│   ├── update_state.py       # Hook state updates
│   └── launch_panel.py       # Webview launcher
└── data/
    ├── default_state.json    # Initial state
    ├── achievements.json     # Achievement definitions
    └── evolution_paths.json  # Evolution data

Configuration

Pet settings in plugin.json:

{
  "settings": {
    "data_dir": "data",
    "state_file": "pet_state.json",
    "meal_times": {
      "breakfast": [7, 9],
      "lunch": [12, 14],
      "dinner": [18, 20]
    },
    "sleep_hours": [22, 6]
  }
}

Achievements

Unlock achievements by reaching milestones:

Achievement	Requirement	Reward
Hello World	Create 1 file	50 XP
Bug Squasher	Fix 100 errors	500 XP
Speed Coder	10 consecutive successes	150 XP
Night Owl	Code past midnight	200 XP
Growing Up	First evolution	500 XP

Development

Running the Webview

python scripts/launch_panel.py --webview

Checking Pet State

python scripts/launch_panel.py --status
python scripts/launch_panel.py --json

Adding Custom Sprites

1. Create pixel art at the appropriate resolution
2. Export as JSON with the format in assets/sprites/base_pet.json
3. Add to the sprites directory

Modifying Pet Personality

Edit agents/pet-companion.md to customize how your pet responds!

Technical Details

• Language: Python 3+ for backend, vanilla JavaScript for frontend
• Storage: JSON file persistence
• Rendering: HTML5 Canvas with pixel-perfect scaling
• Animation: requestAnimationFrame at 8 FPS (authentic pixel art feel)

Contributing

Contributions welcome! Areas for enhancement:

• New evolution paths and sprites
• Additional achievements
• Sound effects
• More pet personalities
• Multi-pet support

License

MIT License - feel free to use and modify!

Credits

Created for the Claude Code plugin ecosystem.

---

Happy coding! 🐾✨