mirror of
https://github.com/ghndrx/shellmate.git
synced 2026-02-10 06:45:02 +00:00
cd12435a95
- /api/leaderboard - returns top 10 players - /api/stats - returns total players/games - /api/health - health check - Website now shows live leaderboard with auto-refresh - Nginx proxies /api to container port 8080
♟️ ShellMate
SSH into chess mastery.
ssh play@shellmate.sh
🌐 Website: shellmate.sh
🎮 Play: ssh play@shellmate.sh
📚 Learn: ssh learn@shellmate.sh
👀 Watch: ssh watch@shellmate.sh
Experience chess in your terminal. Play against AI, challenge friends, or master the game with interactive tutorials.
✨ Features
🎮 Game Modes
- vs AI — Challenge Stockfish at adjustable difficulty (beginner → grandmaster)
- vs Player — Real-time PvP matchmaking with ELO ratings
- vs Friend — Private rooms with shareable codes
📚 Learn Mode
- Interactive Tutorials — From absolute basics to advanced tactics
- Move Analysis — AI explains why each move matters
- Puzzle Rush — Tactical training exercises
- Opening Explorer — Learn popular openings with explanations
- Endgame Drills — Master critical endgame patterns
🏆 Compete
- Global ELO leaderboard
- Game history & replay
- Achievements & stats
🚀 Quick Start
# Play a game
ssh play@shellmate.sh
# Learn chess
ssh learn@shellmate.sh
# Spectate live games
ssh watch@shellmate.sh
🖥️ Controls
| Key | Action |
|---|---|
| Arrow keys | Navigate board |
| Enter | Select/Move piece |
h |
Get hint |
u |
Undo move |
n |
New game |
r |
Resign |
q |
Quit |
🏗️ Tech Stack
- Python 3.11+ with type hints
- 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
git clone https://github.com/ghndrx/shellmate.git
cd shellmate
docker compose up -d
Then connect:
ssh -p 2222 play@localhost
See docs/self-hosting.md for configuration options.
🔗 Environments
| Environment | Website | SSH |
|---|---|---|
| Production | shellmate.sh | ssh play@shellmate.sh |
| Staging | staging.shellmate.sh | ssh play@staging.shellmate.sh |
| Development | dev.shellmate.sh | ssh play@dev.shellmate.sh |
🤝 Contributing
- Fork the repo
- Create a feature branch (
git checkout -b feature/awesome) - Commit changes (
git commit -m 'Add awesome feature') - Push to branch (
git push origin feature/awesome) - Open a PR to
develop
See CONTRIBUTING.md for details.
📝 License
MIT
Built with ♟️ by Greg Hendrickson