# ♟️ 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

```bash
# 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

```bash
docker compose up -d
```

See [docs/self-hosting.md](docs/self-hosting.md) for configuration.

## License

MIT

---

*Built with ♟️ by Greg Hendrickson*