Chess Trainer

A web-based chess trainer that combines Stockfish (chess engine) with Claude AI (natural language tutor) to create an interactive learning experience.

Play against the computer at adjustable difficulty levels while an AI tutor explains moves in plain English, highlights dangers, and helps you improve.

Features

• Play vs Stockfish — Skill levels 0-20, from beginner to master
• AI Tutor — Ask questions about the position and get friendly, encouraging explanations powered by Claude
• Move Consequences — The tutor analyses captures and trades before recommending moves (e.g. "that's a bad trade — you'd lose a knight for a pawn")
• Clickable Notation — Chess squares mentioned by the tutor light up on the board when clicked
• Plain English Moves — The tutor describes moves like "move your knight from g1 to f3" instead of just "Nf3"
• Auto Commentary — Claude generates human-style commentary for each move as you play
• Game Summaries — Get a written recap when a game ends
• Multiple Profiles — Netflix-style profile switcher with custom avatars and colours
• Multiple Games — Run several games at different skill levels within each profile
• Full Move History — Every move stored with engine evaluations and commentary
• Undo & Reset — Step back moves or restart a game from scratch
• Threat Detection — The tutor knows which pieces are under attack and warns you
• Dark Theme — Vibrant neon-accented UI with gradients and animations

Tech Stack

Layer	Technology
Chess Engine	Stockfish.js (WASM, runs in Web Worker)
Game Logic	chess.js (move validation, FEN/PGN)
Board UI	cm-chessboard (drag & drop, SVG pieces)
AI Tutor	Claude API via PHP proxy
Backend	PHP REST API
Database	MySQL
Frontend	Vanilla JS (ES modules), CSS custom properties

Quick Start (WAMP)

1. Clone into your WAMP www directory:

   cd C:\wamp64\www
   git clone https://github.com/edmozley/chess.git
   

2. Copy the config template and add your database credentials:

   cp chess/config.example.json chess/config.json
   

   Edit config.json with your MySQL credentials.

3. Run the database setup in your browser:

   http://localhost/chess/db/setup.php
   

4. Open the app:

   http://localhost/chess/
   

5. Create a profile, start a game, and play!

6. (Optional) For AI tutor features, go to Settings and enter your Anthropic API key.

Quick Start (Docker)

git clone https://github.com/edmozley/chess.git
cd chess
docker-compose up --build -d

Then visit:

• http://localhost:8080/db/setup.php — create the database tables
• http://localhost:8080/ — open the app

The Docker setup includes PHP/Apache and MySQL, no local dependencies needed. To configure the Anthropic API key, use the Settings page in the app.

Configuration

config.json

{
    "db_host": "localhost",
    "db_name": "chess",
    "db_user": "root",
    "db_pass": ""
}

This file is gitignored. Copy config.example.json to get started.

In Docker, config.json is auto-generated from environment variables (DB_HOST, DB_NAME, DB_USER, DB_PASS).

Anthropic API Key

Set via the Settings page in the app. Stored in the database, not in files. Required for:

• AI tutor chat
• Move commentary
• Game summaries

The app works without an API key — you just won't have the AI features.

How It Works

Player makes a move
        |
        v
chess.js validates it
        |
        v
Stockfish analyses the position (top 3 moves, evaluations, threats)
        |
        v
Results sent to Claude API with board context
        |
        v
Claude translates Stockfish's analysis into friendly English
        |
        v
Player sees: "Nice move! Stockfish agrees. Your knight on f3 controls
              the center and keeps pressure on their pawn."

Stockfish is the chess brain. Claude is the friendly coach. Claude never tries to analyse chess positions itself — it only explains what Stockfish tells it.

Project Structure

chess/
├── index.php              # SPA entry point
├── config.example.json    # DB config template
├── .htaccess              # Apache URL rewriting
├── Dockerfile             # Docker: PHP/Apache image
├── docker-compose.yml     # Docker: app + MySQL
├── docker-entrypoint.sh   # Docker: generates config.json
├── includes/
│   ├── Database.php       # PDO singleton
│   └── Claude.php         # Claude API wrapper
├── api/
│   ├── profiles.php       # Profile CRUD
│   ├── games.php          # Game management
│   ├── moves.php          # Move recording
│   ├── tutor.php          # AI tutor chat
│   ├── commentary.php     # Move commentary
│   └── settings.php       # API key management
├── db/
│   └── setup.php          # Database table creation
└── assets/
    ├── css/               # Dark theme stylesheets
    ├── js/                # SPA modules
    ├── lib/               # Self-hosted libraries
    │   ├── chess/         # chess.js
    │   ├── cm-chessboard/ # Board UI
    │   └── stockfish/     # Stockfish.js engine
    └── img/               # Favicon, avatars

License

MIT