Install Guide

Get ChessBot running in under 5 minutes. You'll need Git, Python 3, and Chrome.

0 Prerequisites

Python is used to run the local WebSocket server that bridges the Chrome extension to the Stockfish engine. No pip packages required — it uses the standard library only.

1 Clone the Repository

Open a terminal and clone the ChessBot repo:

git clone https://github.com/matisseduffield/chessbot.git
cd chessbot

This gives you everything — the extension source, the WebSocket server, Stockfish binaries, opening books, and tablebases.

2 Start the Server

Run the WebSocket server that connects the extension to Stockfish:

python server.py

You should see output like:

ChessBot WebSocket Server
Stockfish engine loaded
Listening on ws://localhost:8765
The server runs locally on port 8765 by default. It communicates with Stockfish via UCI protocol and relays analysis back to the extension over WebSocket. The dashboard UI is served on localhost:8080.

3 Load the Extension

  1. Open Chrome and go to chrome://extensions
  2. Enable Developer mode (toggle in the top-right corner)
  3. Click "Load unpacked"
  4. Select the chessbot/extension folder from the cloned repo

The ChessBot icon should now appear in your extensions bar. Click it to open the popup and verify the connection status shows "Connected".

4 Start Playing

Open any supported chess site:

Start or load a game. ChessBot automatically detects the board and begins analysis. Best-move arrows and the eval bar appear directly on the board.

5 Using the Dashboard

Open localhost:8080 in your browser to access the full dashboard. From here you can:

  • Configure engine settings — depth, MultiPV lines, hash size, threads
  • Toggle analysis overlays — arrows, eval bar, WDL bar, opponent arrows
  • Set up auto-move with humanized delays and suboptimal move chances
  • Enable training mode with progressive hints
  • Choose opening books and endgame tablebases
  • Pick an accent color to theme the entire UI

All settings are saved automatically and persist across sessions.

6 Hotkeys

Alt+AResume analysis
Alt+SStop analysis
Alt+WAnalyze for me
Alt+QAnalyze for opponent

7 Troubleshooting

Popup shows "Disconnected"

Make sure server.py is running in your terminal. Check that nothing else is using port 8765. The server must be running before the extension can connect.

No arrows appear on the board

Refresh the chess page after starting the server. Check the extension popup — analysis must be enabled (not paused). Some ad blockers may interfere with the content script injection.

Engine seems slow

Open the dashboard and check the engine settings. Lower the depth or reduce MultiPV lines if your CPU is struggling. You can also increase the thread count if you have a multi-core processor.

Variant not detected

ChessBot auto-detects the variant from the page. If it's not picking it up, try refreshing. For Fairy-Stockfish variants, ensure the Fairy-Stockfish binary is in the expected path (check the server terminal output).

View on GitHub