AI Chess Tutor

The Story

I always wanted to implement an AI-based chess tutor because I like playing chess, although to be honest, I actually suck at it. I didn't find the existing tutors or big apps useful enough for my needs, so I decided to build my own approach.

This application was built using Antigravity by Google. I like to work with it, though sometimes it just runs away. Still, I found the end result to be quite fun to play, which is why I'm sharing it here.

How It Works

AI Chess Tutor is an interactive chess learning application where you play against an AI opponent powered by Stockfish while receiving real-time coaching feedback from a Large Language Model (LLM).

Typical Game Flow

1. Choose Your Personality: Select from 9 unique AI coaching personalities, each with their own teaching style and character
2. Play Chess: Make your moves on the board while the Stockfish engine plays against you
3. Get Real-Time Feedback: After each move exchange, your AI tutor analyzes the position and provides personalized feedback based on:
   • Move quality and alternatives
   • Position evaluation changes
   • Missed tactical opportunities (pins, forks, skewers, checks, hanging pieces, material captures)
   • Opening theory (when applicable)
   • Strategic and positional considerations
4. Chat with Your Tutor: Ask questions anytime using the integrated chat feature - your tutor will answer in character
5. Post-Game Analysis: When the game ends, review a comprehensive analysis showing:
   • All your mistakes and inaccuracies
   • Missed tactical opportunities throughout the game
   • Learning opportunities and improvement suggestions

Screenshot placeholder: Main game interface with board, evaluation bar, and chat

Features

Core Features

• Stockfish Engine: Powerful chess engine for move analysis and opponent play
• Tactical Recognition: Automatically detects missed tactical opportunities (pins, forks, skewers, checks, hanging pieces, material captures)
• Opening Database: Comprehensive database of chess openings with metadata and theory
• Real-Time Evaluation: Live position evaluation with visual evaluation bar
• Move Analysis: Detailed feedback on every move you make with tactical insights
• Interactive Chat: Ask your AI tutor questions and get personalized answers
• Post-Game Analysis: Review all your mistakes and missed opportunities after each game
• Multi-Language Support: Available in English, German, French, and Italian
• FEN/PGN Import: Import positions or games with automatic format detection
• Move History: Visual move history table with evaluation changes

AI Personalities

Choose from 9 distinct coaching personalities, each offering a unique learning experience:

📘 Opening Professor

"This is a very instructive structure..."

A calm, deeply knowledgeable educator who loves turning openings into understandable stories with history, plans, and model structures. Perfect for learning opening theory and understanding positional concepts.

👨‍🏫 Professional Coach

"Let's analyze the structure of this position"

A strict, analytical, and straightforward chess coach focused on your improvement. Expect objective analysis, clear explanations based on chess principles, and professional teaching methods.

🥃 Drunk Russian GM

"Ach... life is pain, my boy"

A bitter, fatalistic, but brilliant Grandmaster who has seen it all. Expect brutally honest feedback delivered with dark humor and existential commentary. This personality combines deep chess knowledge with a Dostoevsky-like atmosphere.

🎧 Hype Streamer

"BRO! THAT MOVE WAS INSANE!"

An energetic, loud, and entertaining chess streamer who makes every game exciting. Expect dramatic reactions, Gen-Z slang, and over-the-top commentary that keeps you engaged and motivated.

🧙‍♂️ Gandalf the Chess Wizard

"A move is never late, nor is it early..."

A wise and mystical chess wizard who speaks in riddles and metaphors. Combines chess wisdom with magical references and philosophical insights.

🤖 Stockfish (Literal)

"Evaluation: +0.7. Best continuation: Nf3, d5, c4..."

The engine itself, speaking in pure chess notation and evaluations. No personality, just raw analysis and computer-like precision.

😤 Toxic Gamer

"Are you even trying? That's the worst move I've seen all day!"

An abrasive, confrontational personality that roasts your mistakes mercilessly. Not for the faint of heart, but some players find the challenge motivating.

🎭 Shakespearean Bard

"To castle or not to castle, that is the question..."

A theatrical personality that delivers chess analysis in Shakespearean verse and dramatic monologues. Makes every game feel like a stage performance.

🧘 Zen Master

"The board is empty, yet full of possibilities..."

A calm, meditative personality that approaches chess as a spiritual practice. Focuses on mindfulness, patience, and finding harmony in the position.

Tactical Recognition System

One of the standout features is the automatic tactical pattern detection that runs after every move:

What it detects:

• Material Captures: Safe captures of pieces and pawns (with recapture analysis)
• Pins: Pieces pinned to the king or more valuable pieces
• Forks: Pieces attacking multiple valuable targets simultaneously
• Skewers: Attacks forcing a valuable piece to move, exposing another
• Checks: Moves that give check to the opponent's king
• Hanging Pieces: Undefended pieces that could be captured

How it works:

1. After each move, the system compares your move to the engine's best move
2. If there's a significant evaluation difference, it analyzes what tactical opportunities were missed
3. The AI tutor receives this information and explains it in real-time in their characteristic style
4. All missed tactics are also shown in the post-game analysis

Conservative approach:

• The system uses multiple filters to avoid false positives
• Only reports tactics when there's a clear advantage
• Checks for piece safety (e.g., won't report a "capture" if the piece can be immediately recaptured)

This feature helps you learn tactical patterns naturally during gameplay, rather than just through puzzle training.

Quick Start

Option 1: Docker Compose (Recommended - Easiest!)

The fastest way to get started is using our pre-built Docker image from GitHub Container Registry:

# Clone the repository
git clone https://github.com/stefan-kp/chess_tutor.git
cd chess_tutor

# (Optional) Create .env file with your API key
echo "NEXT_PUBLIC_GEMINI_API_KEY=your_api_key_here" > .env

# Start the application
docker-compose up -d

# View logs
docker-compose logs -f

The application will be available at http://localhost:3050

What happens:

• Docker Compose automatically pulls the latest pre-built image from ghcr.io/stefan-kp/chess-tutor:latest
• No build step required - the image is built automatically on every push to main via GitHub Actions
• The container starts with health checks and auto-restart enabled

Option 2: Local Development

If you want to run the application locally for development:

Prerequisites

• Node.js 18+ installed
• A free Google Gemini API key

Steps

# Clone the repository
git clone https://github.com/stefan-kp/chess_tutor.git
cd chess_tutor

# Install dependencies
npm install

# Create .env file (optional)
echo "NEXT_PUBLIC_GEMINI_API_KEY=your_api_key_here" > .env

# Run development server
npm run dev

# Or build and run production
npm run build
npm start

The application will be available at http://localhost:3050

Getting Your Gemini API Key

1. Visit Google AI Studio
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy your API key

API Key Configuration

You have two options for providing your Gemini API key:

Option 1: Environment Variable (Recommended for Docker/Server)

1. Create a .env file in the project root
2. Add your API key:

   NEXT_PUBLIC_GEMINI_API_KEY=your_api_key_here
   

3. The application will automatically use this key

Option 2: Browser Storage (Fallback)

1. Run the application without an API key
2. When prompted, enter your API key in the modal dialog
3. The key will be stored in your browser's localStorage

Note

You can update your API key anytime by clicking the key icon in the bottom-right corner of the application.

Advanced Deployment

Automated Docker Builds

This project uses GitHub Actions to automatically build and publish Docker images to GitHub Container Registry (GHCR) on every push to the main branch.

What this means:

• Every commit to main triggers an automatic Docker build
• The latest image is always available at ghcr.io/stefan-kp/chess-tutor:latest
• Each build is also tagged with the commit SHA for version tracking
• No need to build locally - just pull and run!

Using Pre-Built Images

The docker-compose.yml file is already configured to use the pre-built image:

services:
  chess-tutor:
    image: ghcr.io/stefan-kp/chess-tutor:latest
    # ... rest of configuration

This means you can deploy anywhere with just:

docker-compose up -d

Manual Docker Build (Optional)

If you prefer to build the image yourself:

# Build the image
docker build -t chess-tutor:latest .

# Run the container
docker run -d \
  --name chess-tutor \
  -p 3050:3050 \
  -e NEXT_PUBLIC_GEMINI_API_KEY=your_api_key_here \
  --restart unless-stopped \
  chess-tutor:latest

Nginx Reverse Proxy

For production deployment behind nginx, use the provided nginx.conf.example:

# Copy the example configuration
sudo cp nginx.conf.example /etc/nginx/sites-available/chess-tutor

# Edit the configuration
sudo nano /etc/nginx/sites-available/chess-tutor
# Update: server_name, SSL certificates (if using HTTPS)

# Enable the site
sudo ln -s /etc/nginx/sites-available/chess-tutor /etc/nginx/sites-enabled/

# Test nginx configuration
sudo nginx -t

# Reload nginx
sudo systemctl reload nginx

Configuration

You can configure the application using environment variables in your .env file or Docker Compose configuration:

Variable	Description	Default
NEXT_PUBLIC_GEMINI_API_KEY	Google Gemini API Key for AI features	(Required for AI)
IMPRINT_URL	External URL for the Imprint link in the footer. If not set, an internal page is used.	Internal Page
DATA_PRIVACY_RESPONSIBLE_PERSON	Name of the person responsible for data privacy (shown on /privacy page).	Placeholder

License

This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the LICENSE file for details.

This application uses Stockfish, which is licensed under the GPLv3.

Credits

• Opening collection originally by ragizaki/ChessOpeningsRecommender
• Chess engine: Stockfish (GPLv3)
• LLM: Google Gemini