Analyze Your Chess

Download your chess games in bulk and discover what sorts of mistakes you make most often.

Install

Run npm i analyze-chess-games.

Create cards

Node.js

const { analyzeChessGames } = require('analyze-chess-games')
const { cards, report } = await analyzeChessGames({
    user: 'felice_golfing',
    count: 100, // Optional number of cards to make
    games:  100, // Optional number of games to analyze
    engineDepth: 18, // Optional engine depth
    blunderThresholdCentipawns: 200, // Optionanal blunder threshold in centipawns
    quiet: false, // Turn off progress bars?
})

Alternately, using Promise syntax:

const { analyzeChessGames } = require('analyze-chess-games')
analyzeChessGames({
    user: 'felice_golfing',
    count: 100, // Optional number of cards to make
    games:  100, // Optional number of games to analyze
    engineDepth: 18, // Optional engine depth
    blunderThresholdCentipawns: 200, // Optionanal blunder threshold in centipawns
    quiet: false // Turn off progress bars?
}).then(({cards, report})=>{
    // Do stuff
})

Here cards is an array of cards from the mistakes you've made, and report is a document with some high-level insights about your play.

CLI

Run

analyze-chess-games analyze --user <chess.com username>  [-t <time control, eg 600 or 600+10>]
[-g <number of games to analyze>] [-d <engine depth>] [-b <centipawn threshold for blunders>] [-c <number of cards] 
[-o output file for cards] [-p output file for report] [-k cache file to write to] [-j cache file to read from]
[--quiet]

For example:

analyze-chess-games analyze --user felice_golfing
-c 100 -o cards.json

The analysis will be performed in parallel in the cloud (up to about 100 games at a time) so even though game analysis can take a while, you won't have to wait too long!

You can run analyze-chess-games help for the complete list of commands.

Development

You will want to create a .env file in the root directory with some parameters. Here is an example file you could use:

CACHE_ANALYSIS=cache/analysis.json
BLUNDER_THRESHOLD_CENTIPAWNS=200
ENGINE_ANALYSIS_DEPTH=18
CHESS_SITE=chess.com
CHESS_USERNAME=felice_golfing
GAME_HISTORY_COUNT=5

LAMBDA_FUNCTION_DEPLOY=blunder-invariants-analyze

Deploy to Lambda

While you can perform analysis locally, this can be slow. So, if you have an AWS account, you can create a Lambda function there named "blunder-invariants-analyze" (or whatever value you set for LAMBDA_FUNCTION_DEPLOY in your .env) and then run bash scripts/deploy_analysis_lambda.sh to set up the lambda function there. (This assume that you have the AWS CLI installed).

Then, you can set the environment variable ANALYZE_IN_LAMBDA=1 to significant speed up analysis. As a rule of thumb, you can can expect a speedup of around 50X (which means you can analyse 50X more games!)