chess-self-coach 0.3.11

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, and drills you on the correct moves with spaced repetition.

Static demo | Documentation | Landing page

How It Works

Your games → Stockfish analysis → Spaced repetition training

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 (bilingual FR/EN, step by step)
3. Ask for your chess.com username (for importing games)
4. Auto-detect your Lichess Studies

CLI Reference

Training (main feature)

# Fetch your games and analyze with Stockfish
chess-self-coach train --prepare                    # 20 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

Repertoire management (secondary)

Also includes tools for managing opening repertoire PGN files synced with Lichess Studies:

chess-self-coach analyze <file.pgn>     # Stockfish analysis with [%eval] annotations
chess-self-coach push <file.pgn>        # push PGN to Lichess Study
chess-self-coach pull <file.pgn>        # pull from Lichess Study
chess-self-coach cleanup [file.pgn]     # remove empty default chapters
chess-self-coach status                 # sync status of all repertoire files
chess-self-coach setup                  # interactive configuration wizard

Data & Privacy

• Your games are fetched from public APIs (Lichess, chess.com)
• training_data.json is 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