🐵 ForkMonkey

Your Digital Pet That Lives Forever on GitHub

Fork a monkey 🐵 → Watch it evolve with AI 🤖 → Breed rare traits 🧬 → Free forever 💸

⚡ Takes 30 Seconds	🤖 Evolves Daily	💸 100% Free	🌳 Join 20+ Monkeys

🎮 See Live Demo • 🍴 Fork Your Monkey • 📖 How It Works

---

🎬 What Is This?

Imagine Tamagotchi meets GitHub meets AI.

Your ForkMonkey is a digital pet that:

• 🏠 Lives in your GitHub repo (you truly own it)
• 🧬 Evolves every night while you sleep (AI decides the changes)
• 👶 Breeds through forking (create children with inherited traits)
• 🏆 Competes on a leaderboard (rarity rankings across all monkeys)
• 💰 Costs $0 forever (runs on GitHub's free tier)

"I bred a LEGENDARY golden monkey on day 23!" — Early Adopter

---

👀 See It In Action

🎮 LIVE DEMO →

View the dashboard, leaderboard, family tree, and community gallery!

---

🚀 Get Your Monkey in 30 Seconds

Step 1: Fork This Repo

Click the big green button below 👇

Step 2: Enable GitHub Actions

Go to Actions tab → Click "I understand my workflows, go ahead and enable them"

Step 3: Run the Genesis Workflow

Actions → "Initialize New Monkey" → "Run workflow" → Wait 30 seconds 🐵

Step 4: Meet Your Monkey!

Your monkey is born! Check the README or visit https://YOUR-USERNAME.github.io/forkMonkey/

---

🧬 Your Monkey

Generation	Age	Mutations	Rarity Score
1	51 days	9	16.7/100

---

✨ Features

🤖 Free AI Evolution

Every night, GPT-4o (via GitHub Models) evolves your monkey. No API key needed!

Day 1: 🐵 Born with random DNA
Day 7: 🐵 Grew sunglasses (RARE!)
Day 30: 🐵 Changed to golden color
Day 100: 🐵 Completely unique creature

🧬 Genetic Breeding

Fork any monkey to create a child that inherits traits:

• 50% from parent
• 50% random mutations
• Rare traits can be inherited!

🏆 Rarity System

Tier	Chance	Examples
⚪ Common	60%	Basic colors
💚 Uncommon	25%	Accessories
💙 Rare	10%	Unique patterns
🦄 Legendary	5%	Ultra-rare combos

💎 Extinct Traits (Gen-Locked)

Some legendary traits are only available in early generations — they become EXTINCT forever:

Trait	Max Generation	Status
🏆 Genesis Aura	Gen 1 only	🔒
👑 Alpha Crown	Gen 1-3	🔒
✨ Founders Badge	Gen 1-5	🔒
🌟 Pioneer Glow	Gen 1-10	🔒

Fork early to get these ultra-rare traits before they're gone forever!

🔥 Evolution Streaks

Keep your monkey evolving daily to build streaks and unlock rewards:

Streak	Reward
🏅 7 days	Week Warrior badge
⚔️ 14 days	Fortnight Fighter
💎 30 days	Diamond Hands
💯 100 days	Century Legend

🌳 Family Tree

Watch the network grow as monkeys breed across GitHub. Your lineage matters!

🏅 Achievements

Unlock 12 achievements: First Hatch, Week Warrior, Diamond Hands, and more!

---

🏆 Leaderboard Preview

Rank	Monkey	Rarity
🥇	richinseattle/forkMonkey	40.0
🥈	springsoftware-io/forkMonkey	35.0
🥉	loukasgr/forkMonkey	31.7
...	Your monkey could be here!	???

View Full Leaderboard →

---

💡 How It Works

┌─────────────────────────────────────────────────────────────┐
│  1. FORK     →    2. EVOLVE    →    3. BREED    →   4. WIN │
│                                                             │
│  🍴 Fork       🤖 AI evolves     👶 Others fork    🏆 Climb │
│  the repo     it every night    your monkey     leaderboard│
└─────────────────────────────────────────────────────────────┘

The secret sauce:

• GitHub Actions = The heartbeat (runs daily, free)
• GitHub Models = The brain (GPT-4o, free)
• GitHub Pages = The face (hosting, free)
• Git commits = The memory (history, free)

Total cost: $0/month forever 🎉

---

🛠️ Development

Click to expand developer docs

Local Setup

# Install dependencies
pip install -r requirements.txt

# Initialize your monkey
python src/cli.py init

# View in web interface
./start_web.sh

# Evolve monkey manually
python src/cli.py evolve --ai

# Show monkey stats
python src/cli.py show

# Generate shareable tweet
python src/cli.py share

# Run tests
pytest tests/

Project Structure

forkMonkey/
├── .github/workflows/      # GitHub Actions (daily evolution, deploy)
├── src/                    # Python backend (genetics, AI, CLI)
├── web/                    # Frontend dashboard
├── monkey_data/            # Your monkey's DNA and history
└── promotion/              # Marketing materials

Optional: Use Claude Instead of GPT-4o

1. Get API key from console.anthropic.com
2. Add secret: ANTHROPIC_API_KEY
3. Add variable: AI_PROVIDER = claude

---

🍴 This Monkey Wants Siblings!

Fork this repo to create a child monkey!

Your child inherits traits from this monkey + gets random mutations.

🧬 Notable Traits: Fractals (rare)

🍴 Fork to inherit these rare genetics!

🔥 Breeding boost active! Fork now for enhanced trait inheritance.

Will you breed the next Legendary? 🦄

"Best GitHub project I've seen this year" — Developer

---

🌟 Join the Community

• ⭐ Star this repo to follow updates
• 🍴 Fork to adopt your own monkey
• 🐦 Share on Twitter with #ForkMonkey
• 💬 Open an issue with questions or ideas

---

📜 License

MIT License — Fork, breed, and evolve freely!

---

Your monkey is unique. Your monkey is alive. Your monkey is forever on GitHub.

🎮 Live Demo • 🍴 Fork Now • ⭐ Star