lichess-org

Chess Coach for Young Talents An offline chess coach that explains your games the way an annotated games book does: few comments, on the moments that matter, in plain language. Everything runs on your own machine. No internet, no accounts. github.com/amryounis/chesscoach/blob/main/docs/re… A comment from a real review (qwen3:14b, Homer vs Fritz), unedited: ### 11...bxc4 — Excellent (punished the opponent's mistake) What happened: Black captures White's bishop on c4 with the pawn from b5. This move exploits White's previous mistake by capturing the bishop on c4, which was already under attack and left undefended. It removes a key White piece and strengthens Black's position by creating a clear threat against the White pawn on g6, which is now hanging and vulnerable. What now: White will likely capture Black's pawn on f7 with the pawn from g6, giving check. Black should respond by moving the king to f8, which is the only safe square, and then prepare to defend against White's queen moving to c2. (Earlier versions of this README showed 8...Bg4 "opens the f-file". The f-file opens two moves later, after 9.hxg6 fxg6, and the checker let it through. It now checks what a sentence says the move itself did on the position right after the move.) The idea: the language model only narrates amryounis/chesscoach Small local language models cannot calculate chess, and they cannot read FEN. Asked to analyse a position, they invent pieces, pins and variations. So chesscoach never asks them to. Each part does only what it is good at: |Part|Job| |:-|:-| |Stockfish|Evaluates positions and finds the best moves| |Maia 3|Predicts what a human would play, to tell hard moves from natural ones| |python-chess|Turns positions into verified facts: what a move captured, which pieces it stopped defending, how the position two moves later differs from the engine's line| |Stockfish, again|Verifies the concepts behind a moment: what each side really threatens, what a piece was holding together, which facts matter most| |Local LLM (Ollama)|Rewrites those facts as a coach's comment, and nothing else| The move labels (Excellent … Blunder), who played the move, the size of the advantage and the first sentence of each comment are all computed in code. What the model writes is then checked against the board, as far as code can read it: a piece it places on a square, an attack or defence between named pieces, a pin, a fork and which pieces it hits, a king's pawn shelter, a file opened, material, and legal-move counts. A claim passes if it holds before or after the move or along the engine's line, so a consequence two moves later counts ("8...Bg4 ... opens the f-file" passes because of 9.hxg6 fxg6). A false claim goes back to the model with the correction for one rewrite; if it is still false, the sentence is removed. What is not checked: judgements code cannot parse, such as "a strong attack", "the initiative", "a weak square" or "passive", and any sentence whose wording the checker does not recognise. Those are the model's words. The coach says less rather than something false about the pieces; its strategic opinions still need a reader's eye. The app says this under every comment. Requirements amryounis/chesscoach - Python 3.10+ - Stockfish - Ollama with a model pulled, e.g. ollama pull qwen3:14b (fits a 12 GB GPU; smaller 7–8B models invent noticeably more) - Optional: Maia 3 for human-move prediction - Optional: a Polyglot opening book (.bin), so opening theory is skipped Install amryounis/chesscoach git clone amryounis/chesscoach cd chesscoach pip install -e ".[gui]" # or just pip install -e . for the command line only Configure amryounis/chesscoach chesscoach config --init # writes a commented config file chesscoach config # shows the settings in effect Set at least stockfish_path. Settings can also come from environment variables (CHESSCOACH_STOCKFISH_PATH, CHESSCOACH_MODEL, …) or flags (--stockfish, --book, --model, --depth). Use the desktop app amryounis/chesscoach chesscoach gui (or the chesscoach-app shortcut, which opens without a console window) - Review: open a PGN, choose whose moves to comment on, and review. Stockfish analyses every position, then the coach writes about the critical moments. Moves carry the usual marks (?! inaccuracy, ? mistake, ?? blunder, ! a strong find); on a mistake, Show the better move puts the position before it on the board with your move in red and the engine's in green. Arrow keys step through the game. - Play: a training game against Maia at the rating you choose. Maia plays like a human of that strength, mistakes included. When the game ends, Review this game sends it straight to the coach. Without Maia the opponent is Stockfish, which can't play below 1320 and plays like an engine; the setup screen says so, with its real strength, before you start. - Practice: your inaccuracies, mistakes and blunders from reviewed games come back as positions to solve. Make a move; Stockfish judges it (another move that keeps your chances counts), then you see the engine's move, its line and what the coach said in the review. Exercises you miss come back first. Choose the game you just reviewed or all your reviewed games. - Explain this position / Ask the coach: under the comment, for any move of the open game. The coach explains the position, or answers a question such as "Why not Nd2?", "Is my bishop safe?" or "After Re1+ Kd8 Ne5, does the knight fork anything?". It cannot see the board: code works out what the question needs, gathers verified facts and writes the verdict (which move is better, whether a piece is attacked); the model explains, and its answer is checked against the board before you see it. - Game summary: at the top of a finished review, written by code from the stored facts of each move: your errors, the biggest swing, the themes that recur ("three of your errors weakened your king's pawn shelter"), and below it the patterns across your reviewed games (chesscoach patterns on the command line). Every line can show the facts it rests on. - Games: every game you play or review is kept as ordinary PGN files (Played.pgn, Reviewed.pgn, and any file you add), searchable by player, event or opening and sortable by column; a reviewed game opens with its review. The opening explorer shows what was played in each position of your games and how it scored, for you as White or as Black. - Save PGN… after a review: the game with ?!/?/?? marks, [%eval] on every move, the coach's comments and the engine's better line as a variation on every error, for ChessBase, Lichess, Lucas Chess or SCID. Each side's accuracy (Lichess's method) and the tactical motifs each error allowed or missed (fork, pin, skewer…) are in the review and the PGN. - Settings: engine paths, model, your name and rating, the games folder, saved to the user config file. The board is chessground (Lichess's board), bundled so the app works offline. Study an opening book (once, overnight) amryounis/chesscoach Coaches tell young players not to memorise opening lines but to understand the ideas behind them. chesscoach book study walks a Polyglot opening book (the one in Settings, or a file you give) and has the coach explain the idea of every popular move: what it develops, which central squares it takes, what it prepares, how it fits the opening's typical plan and the book's main answers. Every comment is built from facts code works out and goes through the board check. The opening explorer (Games tab) then shows, in each position, the book's moves with how often they are played, Stockfish's verdict, the idea of each move (hover it), and your own record with it. chesscoach book study --dry-run # how many moves, and roughly how long chesscoach book study # run it; Ctrl+C to stop, run again to go on chesscoach book show "e4 e5 Nf3" # what the study says about a position A full book has far more positions than a local model can comment on, so the study follows only the lines that are played: a move the book gives at least 5% of a position (--min-share), a line while it stays above 0.2% of games (--min-line), up to 20 half-moves (--plies), each position once. With a typical book that is about 500 positions and 750 moves, a few hours with qwen3:14b on a 12 GB GPU. Raise or lower the limits to taste; what is written is kept. Use from the command line amryounis/chesscoach chesscoach review mygame.pgn --side black This writes mygame_annotated.md: every move with its label, then comments on the critical moments only: - the first move out of the opening book - inaccuracies, mistakes and blunders, with what the better move kept - the only good move, when you found it and it wasn't obvious - punishing your opponent's mistake - checkmate Any position, without a game file: chesscoach explain --moves "1. e4 e5 2. Nf3 Nc6 3. Bc4 Nd4" chesscoach ask "Can White take the pawn on e5?" --moves "1. e4 e5 2. Nf3 Nc6 3. Bc4 Nd4" --show-tools Other options: --every-move to comment on every non-book move, --model A --model B to compare models on the same prompts, --verbose to print every prompt. chesscoach demo runs two fixed test positions, which is a quick way to try a new model. Measure it: answer keys amryounis/chesscoach chesscoach eval # facts layer only, no model chesscoach eval -m qwen3:14b --mode pipeline --mode raw --report eval.md chesscoach eval --key rook-check --text reply.txt # score any pasted reply Each answer key is a position whose correct explanation is known: the facts it must mention, and the false claims models have actually made ("material is equal", "the knight forks the rook on b7"). eval reports how many required facts the facts layer supplies, how many the model's text states, and every false claim or invented piece. pipeline scores our annotation; raw scores the model given only the FEN and Stockfish's lines, which is the comparison that shows what the facts layer is worth. Keys live in src/chesscoach/answer_keys/; add your own with --keys. Development amryounis/chesscoach pip install -e ".[dev]" pytest # engine tests are skipped if Stockfish isn't found ruff check src tests Package layout (src/chesscoach/): |Module|Responsibility| |:-|:-| |config|settings from defaults, config file, environment, flags| |engine|Stockfish analysis, Maia prediction| |assessment|win probability, move labels, verdict wording| |describe|moves, effects and boards in plain English| |facts|Tier 1 facts: named material, castling, undefended pieces, legal moves, following a line| |features / tactics|positional and tactical facts; comparing two lines| |prompts / narrator|prompt building, LLM calls, output check and retry| |grounding|checks the claims it can parse (pieces, attacks, pins, forks, shelter, files, material) on the board; judgements are not checked| |concepts|engine-verified threats, piece roles, equal moves, ranked key facts| |coach|"Explain this position", and the "Ask the coach" agent with its fact tools| |opening / moments|book detection, choosing what to comment on| |review / report|whole-game review (structured data) and the markdown report| |play|training games against Maia (or limited Stockfish)| |gui|desktop app: api.py (Python side), static/ (page), app.py (window)| |evaluate|answer-key harness (chesscoach eval)| |accuracy / motifs / classify|accuracy %, tactical motifs in engine lines, !! ! !? and the counts| |library|your games: PGN files with an index, saved reviews, the opening explorer| |pgn_export|the reviewed game as an annotated PGN| |practice|your mistakes as exercises| |history / summary|patterns across games; the game summary| |logfile|chesscoach.log: errors and review timings| |cli|the chesscoach command| Roadmap amryounis/chesscoach Done: game review with critical moments, opening-book skipping, labels from win probability, a facts layer with engine-verified threats and piece roles, a board check on the claims code can parse, an answer-key harness, "Explain this position" and "Ask the coach", and the desktop app with review and play against Maia. Also done: game summaries, recurring themes across your games, and practising your own mistakes. Next: a quicker review mode for modest hardware, a board editor / FEN import so the coach can explain any position, and an easier first-run setup. License amryounis/chesscoach GPL-3.0-or-later. chesscoach uses python-chess and chessground, both GPL-3.0.An offline chess coach that explains your games the way an annotated games book does: few comments, on the moments that matter, in plain language. Everything runs on your own machine. No internet, no accounts. A comment from a real review (qwen3:14b, Homer vs Fritz), unedited: ### 11...bxc4 — Excellent (punished the opponent's mistake) What happened: Black captures White's bishop on c4 with the pawn from b5. This move exploits White's previous mistake by capturing the bishop on c4, which was already under attack and left undefended. It removes a key White piece and strengthens Black's position by creating a clear threat against the White pawn on g6, which is now hanging and vulnerable. What now: White will likely capture Black's pawn on f7 with the pawn from g6, giving check. Black should respond by moving the king to f8, which is the only safe square, and then prepare to defend against White's queen moving to c2. (Earlier versions of this README showed 8...Bg4 "opens the f-file". The f-file opens two moves later, after 9.hxg6 fxg6, and the checker let it through. It now checks what a sentence says the move itself did on the position right after the move.) The idea: the language model only narrates Small local language models cannot calculate chess, and they cannot read FEN. Asked to analyse a position, they invent pieces, pins and variations. So chesscoach never asks them to. Each part does only what it is good at: Part Job Stockfish Evaluates positions and finds the best moves Maia 3 Predicts what a human would play, to tell hard moves from natural ones python-chess Turns positions into verified facts: what a move captured, which pieces it stopped defending, how the position two moves later differs from the engine's line Stockfish, again Verifies the concepts behind a moment: what each side really threatens, what a piece was holding together, which facts matter most Local LLM (Ollama) Rewrites those facts as a coach's comment, and nothing else The move labels (Excellent … Blunder), who played the move, the size of the advantage and the first sentence of each comment are all computed in code. What the model writes is then checked against the board, as far as code can read it: a piece it places on a square, an attack or defence between named pieces, a pin, a fork and which pieces it hits, a king's pawn shelter, a file opened, material, and legal-move counts. A claim passes if it holds before or after the move or along the engine's line, so a consequence two moves later counts ("8...Bg4 ... opens the f-file" passes because of 9.hxg6 fxg6). A false claim goes back to the model with the correction for one rewrite; if it is still false, the sentence is removed. What is not checked: judgements code cannot parse, such as "a strong attack", "the initiative", "a weak square" or "passive", and any sentence whose wording the checker does not recognise. Those are the model's words. The coach says less rather than something false about the pieces; its strategic opinions still need a reader's eye. The app says this under every comment. Requirements Python 3.10+ Stockfish Ollama with a model pulled, e.g. ollama pull qwen3:14b (fits a 12 GB GPU; smaller 7–8B models invent noticeably more) Optional: Maia 3 for human-move prediction Optional: a Polyglot opening book (.bin), so opening theory is skipped Install git clone amryounis/chesscoach cd chesscoach pip install -e ".[gui]" # or just pip install -e . for the command line only Configure chesscoach config --init # writes a commented config file chesscoach config # shows the settings in effect Set at least stockfish_path. Settings can also come from environment variables (CHESSCOACH_STOCKFISH_PATH, CHESSCOACH_MODEL, …) or flags (--stockfish, --book, --model, --depth). Use the desktop app chesscoach gui (or the chesscoach-app shortcut, which opens without a console window) Review: open a PGN, choose whose moves to comment on, and review. Stockfish analyses every position, then the coach writes about the critical moments. Moves carry the usual marks (?! inaccuracy, ? mistake, ?? blunder, ! a strong find); on a mistake, Show the better move puts the position before it on the board with your move in red and the engine's in green. Arrow keys step through the game. Play: a training game against Maia at the rating you choose. Maia plays like a human of that strength, mistakes included. When the game ends, Review this game sends it straight to the coach. Without Maia the opponent is Stockfish, which can't play below 1320 and plays like an engine; the setup screen says so, with its real strength, before you start. Practice: your inaccuracies, mistakes and blunders from reviewed games come back as positions to solve. Make a move; Stockfish judges it (another move that keeps your chances counts), then you see the engine's move, its line and what the coach said in the review. Exercises you miss come back first. Choose the game you just reviewed or all your reviewed games. Explain this position / Ask the coach: under the comment, for any move of the open game. The coach explains the position, or answers a question such as "Why not Nd2?", "Is my bishop safe?" or "After Re1+ Kd8 Ne5, does the knight fork anything?". It cannot see the board: code works out what the question needs, gathers verified facts and writes the verdict (which move is better, whether a piece is attacked); the model explains, and its answer is checked against the board before you see it. Game summary: at the top of a finished review, written by code from the stored facts of each move: your errors, the biggest swing, the themes that recur ("three of your errors weakened your king's pawn shelter"), and below it the patterns across your reviewed games (chesscoach patterns on the command line). Every line can show the facts it rests on. Games: every game you play or review is kept as ordinary PGN files (Played.pgn, Reviewed.pgn, and any file you add), searchable by player, event or opening and sortable by column; a reviewed game opens with its review. The opening explorer shows what was played in each position of your games and how it scored, for you as White or as Black. Save PGN… after a review: the game with ?!/?/?? marks, [%eval] on every move, the coach's comments and the engine's better line as a variation on every error, for ChessBase, Lichess, Lucas Chess or SCID. Each side's accuracy (Lichess's method) and the tactical motifs each error allowed or missed (fork, pin, skewer…) are in the review and the PGN. Settings: engine paths, model, your name and rating, the games folder, saved to the user config file. The board is chessground (Lichess's board), bundled so the app works offline. Study an opening book (once, overnight) Coaches tell young players not to memorise opening lines but to understand the ideas behind them. chesscoach book study walks a Polyglot opening book (the one in Settings, or a file you give) and has the coach explain the idea of every popular move: what it develops, which central squares it takes, what it prepares, how it fits the opening's typical plan and the book's main answers. Every comment is built from facts code works out and goes through the board check. The opening explorer (Games tab) then shows, in each position, the book's moves with how often they are played, Stockfish's verdict, the idea of each move (hover it), and your own record with it. chesscoach book study --dry-run # how many moves, and roughly how long chesscoach book study # run it; Ctrl+C to stop, run again to go on chesscoach book show "e4 e5 Nf3" # what the study says about a position A full book has far more positions than a local model can comment on, so the study follows only the lines that are played: a move the book gives at least 5% of a position (--min-share), a line while it stays above 0.2% of games (--min-line), up to 20 half-moves (--plies), each position once. With a typical book that is about 500 positions and 750 moves, a few hours with qwen3:14b on a 12 GB GPU. Raise or lower the limits to taste; what is written is kept. Use from the command line chesscoach review mygame.pgn --side black This writes mygame_annotated.md: every move with its label, then comments on the critical moments only: the first move out of the opening book inaccuracies, mistakes and blunders, with what the better move kept the only good move, when you found it and it wasn't obvious punishing your opponent's mistake checkmate Any position, without a game file: chesscoach explain --moves "1. e4 e5 2. Nf3 Nc6 3. Bc4 Nd4" chesscoach ask "Can White take the pawn on e5?" --moves "1. e4 e5 2. Nf3 Nc6 3. Bc4 Nd4" --show-tools Other options: --every-move to comment on every non-book move, --model A --model B to compare models on the same prompts, --verbose to print every prompt. chesscoach demo runs two fixed test positions, which is a quick way to try a new model. Measure it: answer keys chesscoach eval # facts layer only, no model chesscoach eval -m qwen3:14b --mode pipeline --mode raw --report eval.md chesscoach eval --key rook-check --text reply.txt # score any pasted reply Each answer key is a position whose correct explanation is known: the facts it must mention, and the false claims models have actually made ("material is equal", "the knight forks the rook on b7"). eval reports how many required facts the facts layer supplies, how many the model's text states, and every false claim or invented piece. pipeline scores our annotation; raw scores the model given only the FEN and Stockfish's lines, which is the comparison that shows what the facts layer is worth. Keys live in src/chesscoach/answer_keys/; add your own with --keys. Development pip install -e ".[dev]" pytest # engine tests are skipped if Stockfish isn't found ruff check src tests Package layout (src/chesscoach/): Module Responsibility config settings from defaults, config file, environment, flags engine Stockfish analysis, Maia prediction assessment win probability, move labels, verdict wording describe moves, effects and boards in plain English facts Tier 1 facts: named material, castling, undefended pieces, legal moves, following a line features / tactics positional and tactical facts; comparing two lines prompts / narrator prompt building, LLM calls, output check and retry grounding checks the claims it can parse (pieces, attacks, pins, forks, shelter, files, material) on the board; judgements are not checked concepts engine-verified threats, piece roles, equal moves, ranked key facts coach "Explain this position", and the "Ask the coach" agent with its fact tools opening / moments book detection, choosing what to comment on review / report whole-game review (structured data) and the markdown report play training games against Maia (or limited Stockfish) gui desktop app: api.py (Python side), static/ (page), app.py (window) evaluate answer-key harness (chesscoach eval) accuracy / motifs / classify accuracy %, tactical motifs in engine lines, !! ! !? and the counts library your games: PGN files with an index, saved reviews, the opening explorer pgn_export the reviewed game as an annotated PGN practice your mistakes as exercises history / summary patterns across games; the game summary logfile chesscoach.log: errors and review timings cli the chesscoach command Roadmap Done: game review with critical moments, opening-book skipping, labels from win probability, a facts layer with engine-verified threats and piece roles, a board check on the claims code can parse, an answer-key harness, "Explain this position" and "Ask the coach", and the desktop app with review and play against Maia. Also done: game summaries, recurring themes across your games, and practising your own mistakes. Next: a quicker review mode for modest hardware, a board editor / FEN import so the coach can explain any position, and an easier first-run setup. License GPL-3.0-or-later. chesscoach uses python-chess and chessground, both GPL-3.0.

Scotch Game for Beginners: Recapture With the Knight By ChessStep editorial team If Black takes your d-pawn in the Scotch Game, your knight can take it back. Your queen can also reach that square, but 4. Qxd4? allows 4...Nxd4, and Black captures your queen. The difference is visible before you move: Black's knight already sits on c6, attacking d4. That is a useful first lesson in this opening. You can challenge the center early, then choose a recapture by checking the pieces around the destination square. For a broader starting point, see the beginner opening guide. > Keep these two decisions together: play d4 to challenge Black's e5-pawn, then, after ...exd4, recapture with the knight from f3. Check Black's possible captures before moving your queen. Start with the central pawn exchange The Scotch Game begins with these moves, as listed in the Lichess opening database: 1. e4 e5 2. Nf3 Nc6 3. d4 exd4 * White's third move sends the d-pawn two squares forward. From d4, it attacks Black's pawn on e5. Black's reply ...exd4 captures that pawn: the black pawn moves diagonally from e5 to d4. Pause here. Your d-pawn has gone, and Black's former e-pawn now occupies d4. White can restore the pawn balance with 4. Nxd4. In this notation, N means knight and x means capture. The knight travels from f3 to d4 and takes the pawn. The exchange has removed one central pawn from each side. Your remaining e-pawn still stands on e4, while your knight occupies d4. You have a concrete position to develop from, without needing to memorize a long variation. Why the knight recapture works After 4. Nxd4, Black's knight on c6 attacks your knight on d4. An attacked piece is not automatically a lost piece. Your queen on d1 protects d4 along the now-open d-file. If Black chooses 4...Nxd4, White can answer 5. Qxd4. Both sides have exchanged a knight. Your queen can now take on d4 without being captured by the c6-knight, because that knight has left the board. 1. e4 e5 2. Nf3 Nc6 3. d4 exd4 4. Nxd4 Nxd4 5. Qxd4 * This line illustrates protection and exchange; Black does not have to trade knights. Another legal continuation is 4...Nf6 5. Nc3. Black develops a knight and attacks e4; White develops the b1-knight to c3, where it protects that pawn. Read each new move before continuing your plan. What goes wrong with 4. Qxd4? Return to the position immediately after 3...exd4. Now try taking the pawn with the queen first: 1. e4 e5 2. Nf3 Nc6 3. d4 exd4 4. Qxd4 Nxd4 5. Nxd4 * Black's knight jumps from c6 to d4 and captures the queen. White's f3-knight can take that knight afterward, but White has exchanged a queen for a knight. Winning back the capturing piece does not repair that loss. The FIDE Laws of Chess, article 3.6, define the knight's move. Here, c6 to d4 is one file across and two ranks down. Look for that jump before choosing your recapture. The warning is specific to this board: moving a queen early can have different consequences in other openings. Practice the recapture decision Try the Scotch Game lesson. Play d4, examine ...exd4, and choose the knight recapture. Then explain what Black could capture if the queen took first. In your next computer game, use the same check whenever a pawn exchange opens a file: which piece should recapture, and what attacks its destination? If you lose material, review the game from the position before the recapture and identify the capture you missed.

Lila: the forever free, adless and open source chess server (19k stars) What it does All text below is quoted directly from the project README. >lichess.org: the forever free, adless and open source chess server lichess.org: - Lila (li[chess in sca]la) is a free online chess game server focused on realtime gameplay and ease of use. - It features a search engine, computer analysis distributed with fishnet, tournaments, simuls, forums, teams, tactic trainer, a mobile app, and a shared analysis board. - The UI is available in more than 140 languages thanks to the community. - Lichess is written in Scala 3, and relies on a modified Play 2.8 framework. - The server is fully asynchronous, making heavy use of Scala Futures and Pekko streams. - Lichess talks to Stockfish deployed in an AI cluster of donated servers. - It uses MongoDB to store more than 12 billion games, which are indexed by elasticsearch. - All rated games are published in a free PGN database. >./lila.sh # thin wrapper around sbt Repository lichess-org/lila Repository stats |Metric|Value| |:-|:-| |Stars|18,900| |Forks|2.8k| |Last release|v1.1.0 (2017-08-31)| |Languages|Scala 62.5%, TypeScript 26.7%, SCSS 7.8%| |Contributors|575| |AI contributor accounts (Claude / Codex / Cursor / Copilot)|None| |AI co-authored commits|Claude: 47, Cursor: 10, Copilot: 5| Main contributor |Field|Value| |:-|:-| |Name|Thibault Duplessis| |GitHub|@ornicar| |Commits to this repo|61,438 (top contributor)| |Company / Location|lichess.org / France| |Followers|6.5k| ────────────────────────────── 📌 How many great GitHub repos have you discovered and completely forgotten about? Don't let another useful tool disappear into your Reddit feed. Get the community's best repos, organized by category, plus key takeaways from real developer discussions, delivered to your inbox twice a week. 📬 Never lose track of great repos again. Subscribe free.

A library to stream Lichess games as GIFs