Chess.com Irwin Analyzer

Cheat detection for Chess.com games using the Irwin machine learning model, originally developed for Lichess.

This is a standalone fork that removes the Lichess integration and MongoDB dependency, providing a simple command-line tool for analyzing Chess.com players.

Note: Irwin was trained on Lichess data. Results on Chess.com games may be less accurate due to different player pools and time control behaviors.

Features

• Fetch games from Chess.com API with caching
• Analyze games with Stockfish (auto-downloads appropriate binary for windows/linux/mac)
• Generate cheat probability reports using pre-trained neural networks
• Incremental analysis (only analyzes new games since last run)
• Checkpoint/resume support for long analysis runs
• Summary reports across multiple players with time control breakdown
• Automatically filters out Chess960 and other variants

Requirements

• Python 3.11+
• Pipenv

Installation

pipenv install

Stockfish will be downloaded automatically on first run.

Configuration

All settings are in conf/config.toml. See conf/config.example.toml for detailed documentation.

[stockfish]
threads = 12       # CPU threads (recommend: cores - 2)
memory = 4096      # Hash table in MB
nodes = 350000     # Nodes per position (higher = slower but more accurate)
update = true      # Auto-download Stockfish

[chesscom]
start_date = ""    # Format: "YYYY/MM" or empty for 1 year ago
end_date = ""      # Format: "YYYY/MM" or empty for today
time_control = ""  # "bullet", "blitz", "rapid", "daily", or empty for all
max_games = 0      # 0 = no limit

[irwin.model.analysed]
file = "modules/irwin/models/analysedGame.h5"

Usage

# Analyze a player (fetches new games since last cache)
pipenv run python chesscom_analyzer.py USERNAME

# Analyze multiple players
pipenv run python chesscom_analyzer.py player1 player2 player3

# Re-fetch games from Chess.com (uses Stockfish checkpoint)
pipenv run python chesscom_analyzer.py --no-cache USERNAME

# Re-run Stockfish analysis from scratch (clears checkpoint)
pipenv run python chesscom_analyzer.py --reanalyze USERNAME

# View summaries
pipenv run python chesscom_analyzer.py --summary              # All players previously analyzed
pipenv run python chesscom_analyzer.py --summary USERNAME     # Specific player

Output

Reports are saved to:

• irwin_report_USERNAME_TIMESTAMP.json - Individual detailed reports
• irwin_summary.json - Summary of all analyzed players
• chesscom_games_cache_USERNAME.json - Cached game data
• analysis_checkpoint_USERNAME.pkl - Resume checkpoint (auto-deleted on completion)

Resuming Analysis

Analysis progress is saved after each game. If you need to interrupt (Ctrl+C) to adjust settings:

1. Stop with Ctrl+C
2. Modify conf/config.toml (threads, nodes, etc.)
3. Re-run the same command - it will resume from where it left off

Use --reanalyze to start fresh (clears the checkpoint).

The checkpoint is automatically deleted when analysis completes successfully.

Interpreting Results

Activation Score	Interpretation
0-20	Normal play
20-40	Slightly elevated (watch list)
40-70	Suspicious patterns
70+	Strong cheat indicators

Credits

• Original Irwin: clarkerubber/irwin by James Clarke
• Pre-trained models from the Lichess Irwin project
• Uses python-chess and Stockfish

License

AGPL-3.0 (same as original Irwin)