# ♟️ ShellMate

**SSH into chess mastery.**

[![CI](https://github.com/ghndrx/shellmate/actions/workflows/ci.yml/badge.svg)](https://github.com/ghndrx/shellmate/actions/workflows/ci.yml)
[![Deploy](https://github.com/ghndrx/shellmate/actions/workflows/deploy.yml/badge.svg)](https://github.com/ghndrx/shellmate/actions/workflows/deploy.yml)

```bash
ssh play@shellmate.sh
```

🌐 **Website:** [shellmate.sh](https://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

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

```bash
git clone https://github.com/ghndrx/shellmate.git
cd shellmate
docker compose up -d
```

Then connect:
```bash
ssh -p 2222 play@localhost
```

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

## 🔗 Environments

| Environment | Website | SSH |
|-------------|---------|-----|
| **Production** | [shellmate.sh](https://shellmate.sh) | `ssh play@shellmate.sh` |
| **Staging** | [staging.shellmate.sh](https://staging.shellmate.sh) | `ssh play@staging.shellmate.sh` |
| **Development** | [dev.shellmate.sh](https://dev.shellmate.sh) | `ssh play@dev.shellmate.sh` |

## 🤝 Contributing

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/awesome`)
3. Commit changes (`git commit -m 'Add awesome feature'`)
4. Push to branch (`git push origin feature/awesome`)
5. Open a PR to `develop`

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## 📝 License

MIT

---

*Built with ♟️ by [Greg Hendrickson](https://gregh.dev)*