Chess Position Analyzer

A real-time chess position analysis tool that connects to live Chess.com games and provides move-by-move evaluation powered by the Stockfish engine. Built as a learning project to explore browser automation, chess engine integration, and DOM parsing.

Note: This project is intended for educational purposes and local analysis only.

---

Key Features

• Live Board Detection — Automatically detects the chess board on Chess.com via DOM parsing
• Real-Time Position Evaluation — Feeds positions to Stockfish and displays evaluation, depth, and best move
• Browser Integration — Connects to Chrome via remote debugging protocol (no extensions required)
• Move Execution — Executes analyzed moves on the board using Selenium ActionChains
• Pawn Promotion Handling — Supports all promotion piece types (queen, rook, bishop, knight)
• Mid-Game Join — Can pick up and analyze games already in progress
• Configurable Engine Settings — Adjustable threads, hash size, and analysis time via config file or CLI

---

Demo

Coming soon

---

Tech Stack

Component	Technology
Language	Python 3.10+
Chess Engine	Stockfish (via UCI protocol)
Engine Interface	python-chess
Browser Automation	Selenium WebDriver
Mouse Control	PyAutoGUI
DOM Parsing	JavaScript injection via Selenium

---

Installation

Prerequisites

• Python 3.10 or higher
• Google Chrome
• Stockfish — download and extract to a known location

Automated Setup (Windows)

git clone https://github.com/yourusername/chess-position-analyzer.git
cd chess-position-analyzer
setup.bat

This will create a virtual environment, install dependencies, and download the matching ChromeDriver.

Manual Setup

git clone https://github.com/yourusername/chess-position-analyzer.git
cd chess-position-analyzer

python -m venv venv
venv\Scripts\pip.exe install -r requirements.txt

Then download ChromeDriver matching your Chrome version and place chromedriver.exe in the project root.

---

Usage

Quick Start (Windows)

run.bat

Manual Start

venv\Scripts\python.exe run.py

CLI Options

python run.py --help

Options:
  --stockfish PATH    Path to Stockfish executable
  --port NUM          Chrome remote debugging port (default: 9222)
  --time SECONDS      Analysis time per move (default: 15)
  --threads NUM       CPU threads for Stockfish (default: all cores)
  --hash MB           Hash table size in MB (default: 2048)

Examples

# Custom Stockfish path
python run.py --stockfish "C:\engines\stockfish.exe"

# Faster analysis (5 seconds per move)
python run.py --time 5

# Limit resource usage
python run.py --threads 2 --hash 512

---

Configuration

Edit config/config.json to set default values:

{
    "stockfish": {
        "path": "C:\\path\\to\\stockfish.exe",
        "threads": 0,
        "hash_mb": 2048,
        "move_time": 15.0
    },
    "chrome": {
        "port": 9222
    }
}

Setting	Description	Default
path	Absolute path to Stockfish executable	(required)
threads	CPU threads for engine (0 = auto-detect all)	0
hash_mb	Transposition table size in MB	2048
move_time	Seconds of analysis per move	15.0
port	Chrome remote debugging port	9222

CLI arguments override config file values.

---

How It Works

Chrome (Chess.com)          Python Application            Stockfish Engine
┌──────────────┐      ┌─────────────────────────┐      ┌──────────────┐
│              │      │                         │      │              │
│  Live Game   │─────>│  BoardReader            │      │              │
│  DOM State   │      │  (JavaScript injection) │      │              │
│              │      │         │                │      │              │
│              │      │         v                │      │              │
│              │      │  Parse SAN moves ──────────────>│  Evaluate    │
│              │      │                         │      │  Position    │
│              │      │  MoveExecutor  <────────────────│  Best Move   │
│  Board UI    │<─────│  (Selenium ActionChains) │      │              │
│              │      │                         │      │              │
└──────────────┘      └─────────────────────────┘      └──────────────┘

1. Browser Connection — Attaches to Chrome via the remote debugging protocol
2. Board Detection — Locates the chess board element in the Chess.com DOM
3. Move Extraction — Reads the move list using injected JavaScript
4. Position Evaluation — Converts moves to FEN and sends to Stockfish via UCI
5. Move Execution — Translates the best move into mouse actions on the board

---

Project Structure

chess-position-analyzer/
├── src/
│   ├── __init__.py
│   ├── main.py              # Core analysis loop
│   ├── engine.py            # Stockfish UCI wrapper
│   ├── browser.py           # Chrome connection utilities
│   ├── board_reader.py      # DOM-based board state reader
│   ├── move_executor.py     # Mouse-based move execution
│   └── logger.py            # Timestamped console logging
├── config/
│   └── config.json          # Default configuration
├── run.py                   # CLI entry point
├── setup.bat                # Automated setup script (Windows)
├── run.bat                  # Quick-launch script (Windows)
├── requirements.txt
├── .gitignore
├── LICENSE
└── README.md

---

Disclaimer

This project is intended for educational purposes and local analysis only. It was built to explore browser automation, chess engine integration, and real-time DOM parsing. Always respect the terms of service of any platform you interact with.

---

Future Improvements

• GUI overlay with real-time evaluation bar
• PGN export for analyzed games
• Multi-platform support (macOS, Linux)
• Analysis-only mode (display best move without executing)
• Position history and move comparison logging

---

License

This project is licensed under the MIT License.