chess-self-coach 0.4.3

Learn from your own chess mistakes: Stockfish analysis + spaced repetition training

Chess Self-Coach

Learn from your own mistakes. Chess Self-Coach fetches your games from Lichess and chess.com, finds your blunders with Stockfish and Lichess tablebases, drills you on the correct moves with spaced repetition, and provides chess.com-quality game review with eval bar, score chart, and move classifications.

Static demo | Documentation | Landing page

How It Works

Your games → Stockfish analysis → Training drills + Game review

The PWA opens on a game list — your recent games from Lichess and chess.com. From there:

• Select games to analyze with Stockfish (checkboxes + batch analyze)
• Click a game for chess.com-style game review (eval bar, score chart, move classifications)
• Train on any analyzed game, or open full Training from the menu for spaced repetition drills across all your mistakes

One command to start

chess-self-coach train --prepare    # fetch games + Stockfish analysis (~5 min)
chess-self-coach                    # open training in browser

What you see

For each mistake in your games, the trainer shows:

• Context: "Middlegame, you had a slight advantage. Your move lost significant material."
• The position with material balance (captured pieces)
• Your task: find the better move by dragging a piece
• Wrong move? Stockfish shows how the opponent punishes it, then Retry
• After answering: explanation, best line (playable), link to the original game
• Spaced repetition: positions come back until mastered (intra-session + SM-2)
• Give up: permanently dismiss positions you don't want to review

Mistake categories

Category	Centipawn loss	Example
Blunder	>= 200 cp	Hanging a piece, allowing checkmate
Mistake	100-199 cp	Missing a tactic, losing material
Inaccuracy	50-99 cp	Passive move when active was better

Endgame positions (≤ 7 pieces) are resolved by the Lichess tablebase API with mathematically exact Win/Draw/Loss verdicts — no Stockfish heuristics needed.

Installation

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/Bobain/chess-self-coach/main/install.sh | bash

Installs Stockfish, Python, pipx, and chess-self-coach. Then run the setup wizard:

chess-self-coach setup

Supported platforms: macOS (Homebrew), Ubuntu/Debian (apt).

Manual installation

# 1. Install Stockfish
sudo apt install stockfish  # or: brew install stockfish

# 2. Install chess-self-coach
pipx install chess-self-coach

# 3. Run the interactive setup wizard
chess-self-coach setup

Update

chess-self-coach update

Setup wizard

The setup command will:

1. Find Stockfish on your system
2. Guide you through Lichess token creation (step by step)
3. Ask for your chess.com username (for importing games)

CLI Reference

Training (main feature)

# Fetch your games and analyze with Stockfish
chess-self-coach train --prepare                    # 10 games, depth 18, parallel
chess-self-coach train --prepare --games 50         # more games
chess-self-coach train --prepare --depth 12         # faster analysis

# Open the training interface
chess-self-coach

# Check your stats
chess-self-coach train --stats

Incremental by default: only new games are analyzed. Existing positions and your SRS progress are preserved.

# Developer options
chess-self-coach train --prepare --fresh            # [dev] discard data, start from scratch
chess-self-coach train --refresh-explanations       # [dev] regenerate texts without Stockfish

Other commands

chess-self-coach syzygy [download|status]  # manage Syzygy endgame tablebases
chess-self-coach setup                  # interactive configuration wizard

Data & Privacy

• Your games are fetched from public APIs (Lichess, chess.com)
• training_data.json and analysis_data.json are stored locally (gitignored)
• Drill progress is in your browser's localStorage
• No server, no account, no tracking

Contributing

See CONTRIBUTING.md for code guidelines.

License

MIT