Better Your Chess

What for?

This project aims to help you learn from all the chess games you've played online, starting with a simple way to download an organized collection of your games!

On, you can view your winrate by color, your best win, and analyze a game per day for free. Building on top of the Stockfish engine and python-chess, this package aims to give the user: winrates by opening, automatic tactic generation from your library, and common deviations from book moves.

Current features:

  • winrate by opening
  • rating distribution

In progress:

  • automatic tactics generation from your library

Future features:

  • show opening positions where you often deviate from book moves
  • loss frequencies (checkmate, resignation, timed out)
  • suggest grandmasters with similar repertoires


  1. notebooks/intro_to_python-chess.ipynb - intro to working with PGNs via python-chess and polyglot opening books.

  2. scripts/ - download games for a user, organized in year/month directories.

    python scripts/ username
  3. chess_analytics/ - implements a GameReader, class to work with PGNs.

  4. chess_analytics/ - build a library of games from a directory, represented as a dataframe with 1 row per game.

    from chess_analytics.game_library import GameLibrary
    library = GameLibrary("data/user_games/user/")


  1. scripts/ - visualize a library: opponent rating distribution, winrate by opening, and more.



  1. scripts/ - Automatically generate tactics from a library. This currently supports mate-in-Ns, producing a JSON and PNGs of the positions. 10 examples are in data/output/tactics/.


White to move & mate in two