shellmate/README.md

♟️ ShellMate

SSH into chess mastery.

ssh play@shellmate.sh

A terminal-based chess experience over SSH. Play against AI, challenge friends, or learn the game with interactive tutorials.

Features

🎮 Game Modes

• vs AI — Challenge Stockfish at adjustable difficulty levels
• vs Player — Real-time PvP matchmaking
• vs Friend — Private rooms with shareable codes

📚 Learn

• Interactive Tutorials — From basics to advanced tactics
• Move Analysis — AI explains why each move matters
• Puzzle Rush — Tactical training exercises
• Opening Explorer — Learn popular openings with explanations

🏆 Features

• ELO rating system
• Game history & replay
• Multiple board themes
• Move hints & analysis
• Chat in PvP games

Quick Start

# Connect and play
ssh play@shellmate.sh

# Spectate a game
ssh watch@shellmate.sh

# Tutorial mode
ssh learn@shellmate.sh

Tech Stack

• Python 3.11+
• Textual — Modern TUI framework
• python-chess — Chess logic & notation
• Stockfish — AI engine
• asyncssh — SSH server
• Redis — Matchmaking & sessions
• PostgreSQL — User data & game history

Self-Hosting

docker compose up -d

See docs/self-hosting.md for configuration.

License

MIT

---

Built with ♟️ by Greg Hendrickson