🐾 Terminal Pet

A virtual pet that lives in your terminal and grows with your coding activity! Your pet gets stronger, happier, and more experienced with every git commit you make.

✨ Features

• 🐱 Multiple Pet Types: Choose from cats, dogs, or dragons
• 📊 Real-time Stats: Health, happiness, hunger, and energy tracking
• 🎯 Git Integration: Your pet grows stronger with every commit
• 🏆 Achievement System: Unlock achievements for coding milestones
• 🎨 Beautiful ASCII Art: Colorful pet visualizations with mood indicators
• 💾 Persistent State: Your pet remembers everything between sessions
• 🔄 Automatic Git Hooks: Optional automatic feeding on commits
• 📈 Coding Analytics: Track your programming patterns and streaks

🚀 Installation

Global Installation (Recommended)

npm install -g terminal-pet

Local Installation

npm install terminal-pet

🎮 Quick Start

1. Adopt your first pet:

   pet adopt

2. Check on your pet:

   pet status

3. Take care of your pet:

   pet feed    # When hungry
   pet play    # When bored
   pet sleep   # When tired

4. Start coding! Your pet will automatically get stronger with every git commit! 🎉

📋 Commands

| Command | Description | |---------|-------------| | pet | Show your pet's current status | | pet adopt | Adopt a new pet (replaces current pet) | | pet status | View detailed pet status | | pet feed | Feed your hungry pet | | pet play | Play with your pet (requires energy) | | pet sleep | Let your pet rest and recover | | pet stats | View achievements and coding statistics | | pet help | Show help information | | pet git-setup | Set up automatic git hooks | | pet git-remove | Remove git hooks |

🐾 Pet Types

🐱 Cat

• Personality: Independent but loving
• Special: Extra happiness from successful commits
• ASCII Art: Classic cat expressions

🐶 Dog

• Personality: Loyal and energetic
• Special: Bonus energy recovery
• ASCII Art: Adorable dog animations

🐉 Dragon

• Personality: Powerful and mystical
• Special: Higher experience gains
• ASCII Art: Majestic dragon poses

📊 Pet Stats Explained

Core Stats

• ❤️ Health (0-100): Overall wellbeing. Decreases if hungry or unhappy for too long
• 😊 Happiness (0-100): Mood level. Increases with play and commits, decreases over time
• 🍖 Hunger (0-100): How hungry your pet is. Increases over time, feed to decrease
• ⚡ Energy (0-100): Activity level. Decreases with play, recovers with sleep

Progression

• Level: Increases with experience points from commits
• Experience: Gained from git commits and good coding practices
• Age: How many days since adoption
• Streak: Consecutive days with commits

🏆 Achievement System

Unlock achievements by reaching coding milestones:

• 🎉 First Commit: Make your first commit with your pet
• 💯 Century Club: Reach 100 total commits
• 🔥 Week Warrior: Maintain a 7-day commit streak
• 🌟 Month Master: Maintain a 30-day commit streak
• 🔟 Double Digits: Reach level 10
• 🎖️ Half Century: Reach level 50
• 🍖 Well Fed: Keep hunger at 0
• 😍 Pure Joy: Achieve 100% happiness

🎯 Git Integration

Terminal Pet integrates with your git workflow to reward good coding practices:

Commit Rewards

• Base XP: 10 points per commit
• Streak Bonus: Up to 20 extra points for consecutive days
• Message Quality: Bonus points for descriptive commit messages
• Commit Type Bonuses:
  • Bug fixes: +5 XP
  • New features: +8 XP
  • Refactoring: +6 XP

Automatic Git Hooks

Set up automatic feeding with git hooks:

pet git-setup

This creates a post-commit hook that automatically rewards your pet after each commit!

🎨 Pet Moods

Your pet's mood changes based on their stats:

• 😊 Happy: Good overall stats
• 🤩 Ecstatic: Excellent health and happiness
• 😢 Sad: Low happiness
• 🍽️ Hungry: High hunger level
• 😴 Tired: Low energy
• 🤒 Sick: Low health
• 💀 Dead: Health reached 0 (adopt a new pet!)

🔧 Advanced Usage

Programmatic Usage

const { Pet, PetDisplay, GitIntegration } = require('terminal-pet');

// Create a new pet
const pet = new Pet('MyPet', 'cat');

// Simulate a commit
pet.onCommit('feat: add awesome feature');

// Display the pet
console.log(PetDisplay.displayPet(pet));

// Save state
pet.save();

Custom Git Integration

const { GitIntegration } = require('terminal-pet');

const git = new GitIntegration();

// Get commit statistics
const stats = await git.analyzeCommitActivity();
console.log('Recent commits:', stats.totalCommits);

// Check if in git repository
const isRepo = await git.isGitRepository();

🛠️ Development

Setup

git clone https://github.com/yourusername/terminal-pet.git
cd terminal-pet
npm install

Testing

# Link for local testing
npm link

# Test commands
pet adopt
pet status

Project Structure

terminal-pet/
├── bin/
│   └── cli.js          # CLI interface
├── lib/
│   ├── Pet.js          # Core pet logic
│   ├── PetDisplay.js   # ASCII art and display
│   └── GitIntegration.js # Git workflow integration
├── package.json
├── index.js           # Main module exports
└── README.md

🤝 Contributing

Contributions are welcome! Here are some ideas:

• 🎨 New pet types and ASCII art
• 🏆 Additional achievements
• 📊 More detailed analytics
• 🎮 Mini-games and interactions
• 🌍 Localization support

Development Guidelines

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Inspired by the classic Tamagotchi virtual pets
• Built with love for the developer community
• ASCII art inspired by various terminal art collections

🐛 Troubleshooting

Common Issues

Pet not responding to commits:

• Ensure you're in a git repository
• Set up git hooks with pet git-setup
• Check that the pet is alive with pet status

Pet died:

• Adopt a new pet with pet adopt
• Remember to feed and play with your pet regularly!

Commands not found:

• Ensure global installation: npm install -g terminal-pet
• Check PATH includes npm global binaries

Support

• 🐛 Report bugs
• 💡 Request features
• 💬 Join discussions

Made with ❤️ for developers who love their code (and virtual pets)!

Remember: A well-fed pet is a happy pet! Keep coding and keep your terminal buddy healthy! 🐾