I Built My Friend a Free, Offline Chess Coach with Stockfish and a Local LLM

Shaurya Srivastava — Sun, 04 Oct 2026 19:42:03 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

I built a chess game analyzer for my friend. He loves chess, but he doesn't play often enough to pay for a subscription just to find out what he did wrong after a game or a puzzle.

His request was simple: "I want software that analyzes my moves and tells me what I did wrong."

So I built that. You upload a game (a PGN file from Lichess or Chess.com), and the app:

marks every move as best, excellent, good, inaccuracy, mistake, or blunder
shows the position with arrows for your move and the engine's better move
explains each mistake in one or two plain sentences
lets you ask a coach questions about the move you are looking at
counts your recurring problems across the game (for example "7 hung pieces")
checks single puzzle positions: enter a position and your move, and it tells you how good the move was

Lichess already offers free engine analysis, so I'm not claiming nobody can analyze games for free. What this adds is plain-language reasons, a summary of repeated mistakes, and a tool that runs locally and keeps the analysis on your machine.

My goal wasn't to build another chess engine. It was to build something that explains mistakes in a way a casual player can learn from.

Demo

Code

shauryasri14 / Chess-Move-Analyzer

A free, offline chess analyzer built for a friend who can't justify paying for game review. Stockfish judges every move, code tags the cause (hung piece, missed capture, missed mate), and a local LLM via Ollama explains it in simple words. Your games never leave your machine.

♟ Chess Move Analyzer

Free, offline chess game review that tells you what you did wrong, in plain language.

Stockfish judges every move, code tags the cause, and a small local LLM (via Ollama) explains it. No account, no subscription, no game limit, and your games never leave your machine.

Built for a friend who loves chess but doesn't play often enough to justify paying for game analysis Submission for the Hacktoberfest Weekend Challenge: Build for a Friend.

Why this exists

Casual players finish a game or a puzzle and want one thing: what did I do wrong? Many tools lock full analysis behind a paid plan, which doesn't make sense for someone who plays a few games a month.

This project gives that analysis for free, on your own computer:

Stockfish (open-source engine) decides which moves were mistakes.
Code finds the likely cause: a hung piece, a missed capture…

View on GitHub

To run it yourself: docker compose up --build, then open http://localhost:8501. Setup without Docker is in the README.

How I Built It

Open-source pieces

Piece	Role
Stockfish	Evaluates each position; the change in evaluation is used to classify the move. One of the strongest open-source chess engines.
python-chess	Reads PGN, builds boards, and communicates with Stockfish
Ollama with `gemma3:4b`	Runs the language model locally to explain mistakes
Streamlit	The web interface
Docker Compose	One command starts the app and Ollama

The pipeline

PGN → Stockfish evaluates each position → code classifies and tags mistakes → local LLM explains → summary

The most important design rule: the model never judges the chess.

Small language models are bad at evaluating chess positions, so the work is split:

Stockfish evaluates each position once. The evaluation after one move is reused as the evaluation before the next.
Code turns the evaluation drop into a label (for example, 300+ centipawns lost is a blunder) and finds the likely cause: a hung piece, a missed capture, or a missed mate.
The LLM receives only these facts and explains them in one or two sentences. It is told not to invent moves.

The "Ask the coach" chat works the same way: every question carries the current position, the evaluations, the engine's line, and the neighbouring moves. A "What the coach sees" panel shows exactly what the model is given, so you can check its input.

Details that mattered

Evaluations are clamped to ±15 pawns, so trimming a huge lead isn't called a blunder.
Thresholds are editable in the sidebar and re-label instantly, with no engine rerun.
If Ollama isn't running, the app falls back to template explanations instead of breaking.

Honest limitations

The cause tags are simple heuristics and can miss exchange sequences or pins.
A 4B model can still phrase things badly sometimes.

Why Does Open Innovation Matter?

The best engine is open source. Stockfish gives strong analysis for free, and paying for analysis was exactly my friend's problem.
No account, subscription, or game limit. He can analyze one game a month or fifty.
His games stay on his machine. The model runs locally and the app works offline.
I could control the coach. With a local model I wrote the system prompt, limited it to engine facts, showed its input, and could swap models freely. A closed API would make that harder and add a cost per question.

My Friend's Reaction

When I first showed my friend the project, his first reaction was, “Bro, this would be way better if it worked directly on Chess.com.” I was like, “Yeah, I know, but at least appreciate what I made!” 😭

A little later, he actually played a game, exported it from Chess.com, and uploaded the PGN to my app. He went through the analysis himself, and once he saw everything actually working, he was genuinely impressed. He liked that he could go through the game move by move and see not just that a move was bad, but what he did wrong and what he could have played instead.

He uses Chess.com quite regularly and usually ends up using his free analysis/trial features pretty early in the month. So being able to just run this locally and analyze his games whenever he wants was something he actually found useful.

DEV Community: Shaurya Srivastava