🐍 Snake Evolution

Turn your GitHub contributions into an animated snake that devours them!

Quick Start • Themes • GitHub Action • CLI • PvP Mode

---

---

⚡ Quick Start

Using npx (zero-install):

npx @snake-evolution/cli@latest generate -u YOUR_USERNAME

Using GitHub Action:

See 🤖 GitHub Action section below.

Local development:

git clone https://github.com/miccy/snake-evolution.git
cd snake-evolution
bun install
npx @snake-evolution/cli generate -u YOUR_USERNAME -o snake.svg

---

✨ Why Snake Evolution?

• 🎨 6 Beautiful Themes - Match your profile's aesthetic (Glass arrives with GIF support)
• 🧠 Smart Pathfinding - Snake hunts high-value contributions first
• ⚡ Zero-Install CLI - npx @snake-evolution/cli@latest - no setup needed
• 🤖 GitHub Action - Automated daily updates
• 📦 Full Monorepo - Engine, renderer, and themes are separate packages
• 🎯 Production Ready - Used by developers worldwide

🎨 Showcase

Explore all available themes:

![GitHub Dark Theme](./assets/examples/github-dark.svg)
<!-- slide -->
![Ocean Theme](./assets/examples/ocean.svg)
<!-- slide -->
![Sunset Theme](./assets/examples/sunset.svg)
<!-- slide -->
![Neon Gamer Theme](./assets/examples/neon-gamer.svg)
<!-- slide -->
![CypherPunk Theme](./assets/examples/cypherpunk.svg)

Real-world examples:

• 💼 Portfolio README animations
• 📚 Documentation sites with contribution graphs
• 🎤 Conference presentation slides
• ✍️ Technical articles and blog posts

---

🎨 Themes

🌑 GitHub Dark (Default)

☀️ GitHub Light

🌊 Ocean

🌅 Sunset

🎮 Neon Gamer

🔵 Cypherpunk

🧊 Glass (Coming Soon)

GIF rendering is still in progress. The Glass theme will unlock once GIF output is available.

---

🤖 GitHub Action

Add to your profile README repository:

.github/workflows/snake.yml

name: Generate Snake

on:
  schedule:
    - cron: "0 0 * * *" # Daily
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  generate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4

      - uses: miccy/snake-evolution@v1
        with:
          github_user_name: ${{ github.repository_owner }}
          outputs: |
            dist/snake.svg
            dist/snake-dark.svg?palette=github-dark
            # dist/snake.gif?palette=ocean&format=gif  # ⚠️ GIF support pending
          theme: github-dark

      - name: Commit and Push
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add dist/*.svg
          git diff --staged --quiet || git commit -m "🐍 Update snake"
          git push

Then in your README.md:

![Snake](./dist/snake.svg)

Outputs input: You can provide multiple outputs separated by commas or new lines. Each entry is written inside github.workspace and can optionally include query params for per-output overrides, e.g. dist/snake.svg?palette=ocean&format=svg.

---

💻 CLI

Zero-Install (Recommended)

No installation required! Use npx or bunx:

# Using npx
npx @snake-evolution/cli@latest generate -u YOUR_USERNAME

# Using bunx (faster)
bunx @snake-evolution/cli@latest generate -u YOUR_USERNAME

# With custom options
npx @snake-evolution/cli@latest generate -u YOUR_USERNAME -t ocean -o snake.svg

Global Installation

# Using npm
npm install -g @snake-evolution/cli

# Using bun
bun add -g @snake-evolution/cli

# Then use anywhere
snake generate -u YOUR_USERNAME
snake themes  # List available themes

Local Project

npm install @snake-evolution/cli
# or
bun add @snake-evolution/cli

Options

Option	Description	Default
-u, --username	GitHub username	required
-o, --output	Output file path	snake.svg
-t, --theme	Color theme	github-dark
-f, --format	Output format (svg only; GIF not supported yet)	svg
-y, --year	Year to generate	current
--static	Static SVG (final frame with snake)	false

ℹ️ GIF output is not available yet. The CLI will stop with a clear error if you request --format gif or the Glass theme.

---

🎮 Coming Soon: PvP Mode

Challenge your friends to snake battles!

• 🏆 Leaderboards - Global rankings
• ⚔️ 1v1 Challenges - Battle friends
• 👥 Team Battles - Company vs company
• ⚡ Power-ups - Shrink, teleport, shield
• 📈 Progressive rounds - Gets faster each level!

📍 View Roadmap →

---

🏗️ Development

git clone https://github.com/miccy/snake-evolution.git
cd snake-evolution
bun install
bun run generate -u YOUR_USERNAME -o test.svg

---

🤝 Contributing

We love contributions! See CONTRIBUTING.md

• 🐛 Report bugs
• 💡 Request features
• 🎨 Submit new themes

---

💖 Support

If you find this useful:

• ⭐ Star this repo - It helps a lot!
• 🐦 Share on Twitter/X - Spread the word
• 💬 Join Discussions - Ideas and feedback

---

📄 License

MIT © Miccy

Original snake concept by Platane 🙏

---

_{Built with 🐍 by @miccy}