Stockfish + Claude

Find the mistakes you keep making.

chess-digest reviews your recent chess.com games. It runs Stockfish on every move, asks Claude which mistakes you keep repeating, and writes a short report with board diagrams and links to practice material.

a8b7c6d5e4f3g2h1
Blunder · middlegame · blitz · 83s left
19. Qc3? #2 → -1.71 missed mate
Best was Qxb6+ 19. Qxb6+ Kb8 20. Qxb7#
1 commandchess analyse --week
~2 KBper board diagram
a few centsof Claude per report
What you get

A coach's notes on your last week

Every report is one HTML file you can open anywhere. It focuses on patterns, not on single bad moves.

Recurring problems

Three to five patterns ranked by how much they cost you, each with a way to fix it.

Your own positions

Boards from your games with your move in red and the engine's move in green.

Study links

Lichess puzzle themes, Lichess practice and Wikipedia pages picked for each problem.

Your numbers

Record, accuracy, blunders per game, openings and mistakes by game phase.

How it works

Engine first, AI second

Stockfish decides what was a mistake. Claude only groups them and explains them.

Fetch

Games come from the chess.com Published-Data API. You don't need to log in.

Analyse

Stockfish checks every position. A drop of 20 points in winning chances is a mistake, 30 is a blunder.

Coach

Claude gets the worst mistakes in one request and can only pick themes and positions that exist.

Report

You get one HTML file. Games from earlier reports are skipped next time.

Set it up

Five minutes with Docker

You need Docker Desktop, git and an Anthropic API key.

any OS
$ git clone https://github.com/VladKhomich/chess-digest.git
$ cd chess-digest
$ cp .env.example .env   # key + username
$ docker compose build
$ docker compose run --rm digest --games 30
PowerShell
# once, in $PROFILE
. "C:\path\to\chess-digest\chess.ps1"

> chess analyse -g 10      # last 10 games
> chess analyse --week     # last 7 days
> chess open               # latest report

Reports land in out/. Add --all to include games from earlier reports, or --no-ai for a free engine-only report.

Publish

Your own report site

Fork the repo and turn on GitHub Pages for the docs folder of main. Then run chess analyse --week --publish.

It commits only docs/digests/ and pushes. Published pages hide your opponents' usernames and ask search engines not to index them.

Cost

Cents, not a subscription

Stockfish runs on your machine. Each report makes one Claude Sonnet call.

That's usually a few cents, and a week of games rarely goes past 25 cents.

See what a week of blitz looks like

54 games, 187 flagged errors and five patterns worth fixing.