ChessHacks Starter Bot

Bot Overview

This repository contains our ChessHacks competition bot, a hybrid engine that combines a fast alpha-beta search with a neural evaluation network (NNUE). The search explores candidate lines with classic pruning techniques, while the NNUE provides a learned evaluation of positions to guide move ordering and scoring. Together, this pairing balances tactical calculation depth with positional judgment, making the bot strong and responsive in real-time play.

At a high level, the bot:

• Generates legal moves and orders them with heuristics to focus the search on promising lines first.
• Searches with alpha-beta pruning to reduce the number of positions evaluated while preserving tactical accuracy.
• Evaluates leaf nodes with NNUE for fast, high-quality scoring of board positions.
• Plugs into the ChessHacks devtools via a Python backend that streams the current game state to the bot and returns the bot’s move.

This codebase placed third overall in the ChessHacks hackathon. The main bot is written in Python, and the NNUE weights are hosted on Hugging Face. The remainder of the README contains details about the ChessHacks Dev environment

---

Directory Structure

/devtools is a Next.js app that provides a UI for testing your bot. It includes an analysis board that you can use to test your bot and play against your own bot. You do not need to edit, or look at, any of this code (unless you want to). This file should be gitignored. Find out why here.

/src is the source code for your bot. You will need to edit this code to implement your own bot.

serve.py is the backend that interacts with the Next.js and your bot (/src/main.py). It also handles hot reloading of your bot when you make changes to it. This file, after receiving moves from the frontend, will communicate the current board status to your bot as a PGN string, and will send your bot's move back to the frontend. You do not need to edit any of this code (unless you want to).

While developing, you do not need to run either of the Python files yourself. The Next.js app includes the serve.py file as a subprocess, and will run it for you when you run npm run dev.

The backend (as a subprocess) will deploy on port 5058 by default.

This architecture is very similar to how your bot will run once you deploy it. For more information about how to deploy your bot to the ChessHacks platform, see the docs.

Setup

Start by creating a Python virtual environment and installing the dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

or however you want to set up your Python.

Then, install the dependencies for the Next.js app:

cd devtools
npm install

Afterwards, make a copy of .env.template and name it .env.local (NOT .env). Then fill out the values with the path to your Python environment, and the ports you want to use.

Copy the .env.local file to the devtools directory as well.

Installing devtools (if you did not run npx chesshacks create)

If you started from your own project and only want to add the devtools UI, you can install it with the CLI:

npx chesshacks install

This will add a devtools folder to your current directory and ensure it is gitignored. If you want to install into a subdirectory, you can pass a path:

npx chesshacks install my-existing-bot

In both cases, you can then follow the instructions in Setup and Running the app from inside the devtools folder.

Running the app

Lastly, simply run the Nextjs app inside of the devtools folder.

cd devtools
npm run dev

Troubleshooting

First, make sure that you aren't running any python commands! These devtools are designed to help you play against your bot and see how its predictions are working. You can see Setup and Running the app above for information on how to run the app. You should be running the Next.js app, not the Python files directly!

If you get an error like this:

Traceback (most recent call last):
  File "/Users/obama/dev/chesshacks//src/main.py", line 1, in <module>
    from .utils import chess_manager, GameContext
ImportError: attempted relative import with no known parent package

you might think that you should remove the period before utils and that will fix the issue. But in reality, this will just cause more problems in the future! You aren't supposed to run main.py on your own—it's designed for serve.py to run it for you within the subprocess. Removing the period would cause it to break during that step.

Logs

Once you run the app, you should see logs from both the Next.js app and the Python subprocess, which includes both serve.py and main.py. stdouts and stderrs from both Python files will show in your Next.js terminal. They are designed to be fairly verbose by default.

HMR (Hot Module Reloading)

By default, the Next.js app will automatically reload (dismount and remount the subprocess) when you make changes to the code in /src OR press the manual reload button on the frontend. This is called HMR (Hot Module Reloading). This means that you don't need to restart the app every time you make a change to the Python code. You can see how it's happening in real-time in the Next.js terminal.