ChessMaster: Building a Personal Chess Coach on Stockfish and Claude

Udit Raj — Wed, 04 Nov 2026 09:01:57 +0000

ChessMaster transforms raw game data into actionable coaching insights. Chess.com and Lichess show you blunders in individual games — ChessMaster detects the systemic patterns that keep repeating across your entire game history and generates a personalized training plan.

Architecture

Next.js 14 frontend communicates with a FastAPI (Python) backend over REST. The backend orchestrates multi-platform game sync, Stockfish engine analysis, cross-game pattern detection, and Claude-powered report generation.

The service layer contains 15+ specialized services — sync, analysis, patterns, time management, tilt detection, rating prediction, endgame classification, opponent scouting, puzzle generation with spaced repetition — all composable through shared filtering patterns.

SQLite with SQLAlchemy ORM handles storage. Smart indexing on played_at, opening_eco, and time_class keeps aggregate queries fast across thousands of games and hundreds of thousands of move analyses.

Multi-Platform Game Sync

Games are fetched from Chess.com (monthly archive endpoints) and Lichess (NDJSON streaming) in parallel with independent error handling — one platform failing doesn't block the other.

Deduplication uses platform + platform_id as a unique constraint. Clock times are extracted from PGN [%clk H:M:S.F] comments for time management analysis. Lichess NDJSON streaming handles large game counts without memory issues.

Optimized Stockfish Analysis Pipeline

The key optimization: single-pass evaluation with carry-forward. Instead of evaluating both the position before and after each move (2 evals per move), the engine evaluates each position once — the eval_after for move M becomes eval_before for move M+1. This cuts engine calls by 50%.

At depth 20, analysis runs ~20 seconds per game. Moves are classified by centipawn loss:

Great: CPL < 10 (best move found)
Good: CPL 10-50
Inaccuracy: CPL 50-150
Mistake: CPL 150-300
Blunder: CPL > 300

A tactical motif detection algorithm uses ray-tracing to identify forks, pins, skewers, discovered attacks, and back-rank threats in blundered positions.

Cross-Game Pattern Engine

The pattern engine aggregates 12+ metrics across all analyzed games to surface systemic weaknesses rather than one-off errors:

Opening performance — win/loss/draw rate per ECO code with average CPL
Worst openings — minimum 3 games, sorted by win rate
Phase accuracy — separate CPL for opening, middlegame, and endgame (using material-based phase detection, not move count)
Phase blunder rate — percentage of blunders per game phase
Missed tactical motifs — forks, pins, skewers, discovered attacks, back-rank threats
Time trouble correlation — blunder rate in normal time vs. under 60 seconds
Color performance — white vs. black win rates and accuracy
Endgame conversion — percentage of won positions (eval >= 200cp) actually converted to wins
Blunder distribution — by move bucket (1-10, 11-20, 21-30, etc.)
Monthly trends — CPL improvement or degradation over time
Streak analysis — win/loss streaks and tilt patterns
Example positions — 10 worst blunders with FEN, CPL, and tactical classification

The same PatternEngine class handles filtering by platform and time class — composable filters reduce code duplication across 8+ analysis modes.

AI Coaching Report

Claude Sonnet generates personalized coaching reports from the pattern data, structured into 5 sections:

Player profile summary
Top 3-5 systemic weaknesses with actual FEN positions from the player's games
Opening repertoire advice based on win rates and CPL
Strengths to build on
30-day training plan with specific exercises

The prompt includes the player's top 15 openings, missed tactical motifs, phase accuracy, time trouble stats, color performance, endgame conversion rates, and actual blunder positions — so advice is specific ("practice forks in K+P endgames when the opponent king is on the rim") rather than generic ("practice tactics").

Time Management Analytics

Time spent per move is calculated from consecutive clock readings. The system detects:

Overthinking: opening moves with <10 CPL loss but >15 seconds spent
Underthinking blunders: moves with >100 CPL loss but <5 seconds spent
Time zone analysis: critical (0-30s), low (30-60s), normal (60-180s), comfortable (180+s)
Time vs. accuracy curves: correlation between time spent and centipawn loss per move bucket

Tilt Detector

Session-based analysis (games within 4 hours grouped as one session):

Win/loss/draw streak tracking with averages
Blunder rate increase after 3+ consecutive losses
Rating drop detection (sessions with >50-point drops)
Auto-generated recommendations ("stop playing after a 3-loss streak")

Rating Predictor

Linear regression on rating vs. days played:

Points-per-month projection
Milestone estimates (when you'll hit 1000, 1200, 1500, etc.)
Momentum comparison: last 30 games vs. prior 30 games
Monthly weakness trends (CPL by phase over time)

Puzzle Training (SM-2 Spaced Repetition)

Every blunder and mistake automatically becomes a training puzzle. The SM-2 algorithm schedules reviews:

Due puzzles first (next_review <= now)
Then never-attempted positions
Then worst blunders (highest CPL)
Ease factor adapts based on success rate: max(1.3, ease_factor + (0.1 - (5 - rating) * 0.08))
Filterable by game phase, tactical motif, platform, and time control

Opponent Scouting

Fetches the opponent's last 100 games, breaks down their opening repertoire by frequency, cross-references against the player's record in those specific openings, and generates preparation recommendations.

15+ services, 17 API routers, 109 backend tests, 19 frontend tests.

What I learned building it

Single-Pass Evaluation Halves Engine Costs — evaluating each position once and carrying forward the result (eval_after for move M = eval_before for move M+1) eliminates redundant Stockfish calls. When processing thousands of games, this 50% reduction is the difference between hours and minutes.
Material-Based Phase Detection > Move Count — classifying game phase by remaining material (opening: fullmove <= 10 AND material >= 50pts; endgame: material <= 26 OR no queens AND material <= 30) handles Chess960, gambits, and unusual openings correctly. Move count fails for any non-standard game.
Cross-Game Pattern Detection Is the Real Value — individual game analysis (blunder classification) is commodity. The insight that changes behavior comes from aggregating across hundreds of games: "you blunder 3x more in endgames than middlegames" or "your fork detection drops 40% when you're in time trouble."
Composable Filters Prevent Service Explosion — the same PatternEngine class handles filtering by platform, time class, and game phase. Without composable filters, each combination would need its own service — 8+ analysis modes would become 24+ services.
SM-2 Spaced Repetition for Auto-Generated Puzzles — every blunder becomes a training puzzle with adaptive scheduling. The algorithm naturally surfaces the hardest problems more frequently while letting mastered positions fade, without manual curation.
Structured LLM Prompts with Real Game Data — generic chess advice is useless. Including actual FEN positions, CPL values, and opponent names in the Claude prompt forces specific, actionable recommendations instead of "practice more tactics."
NDJSON Streaming for Large Datasets — Lichess's NDJSON streaming API handles 1000+ games without buffering the entire response in memory. For any API that returns large collections, streaming prevents memory pressure.
Tactical Motif Detection via Ray-Tracing — detecting forks, pins, skewers, and discovered attacks by tracing attack lines from piece positions is computationally elegant. No need for ML — pure algorithmic detection on the board state.
Session-Based Tilt Detection — grouping games within 4-hour windows as sessions and tracking blunder rate increase after consecutive losses quantifies tilt. This turns a subjective feeling ("I'm playing badly") into actionable data ("your blunder rate increases 60% after 3 losses — stop playing").
Platform-Agnostic Data Normalization — unifying Chess.com and Lichess into a common schema at the ingestion layer means every downstream service (analysis, patterns, reports) works identically regardless of source. Add a third platform and nothing downstream changes.

Source: https://github.com/uditrajmr3/chessmaster

Originally published on uditraj.site — from the Workshop.

DEV Community: Udit Raj