Metadata-Version: 2.4
Name: claude-pet-companion
Version: 1.0.0
Summary: A pixel-art virtual pet plugin for Claude Code
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 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.

![Pet Companion](https://img.shields.io/badge/Pet-Companion-purple)
![Version](https://img.shields.io/badge/version-1.0.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)

## 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**
   ```bash
   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`:

```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

```bash
python scripts/launch_panel.py --webview
```

### Checking Pet State

```bash
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! 🐾✨
