Blunderchess

A UCI chess engine

Core principle is simplicity, using generic chess principles rather than specific micro-optimizations.

This is an AI-first project. The code is 100% generated by agents based on continuously refined architecture reference. See docs/adr/*.md

Development process

After the initial phase of specification, autonomous code generation, and fixing of initial quirks, the next phase is fully automated improvements:

• play against stronger engine, analyze with strongest engine
• find gamplay problems
• formulate plan for improvement, solve, reproduce by tests
• verify - then accept or deny change

NNUE is for now out of scope. The intention is to rely on a simple - but still effective - explicit evaluation.

Identified challenges:

• simulations are timeconsuming
• training data issues: strong engine's strong/weak moves are sometimes only obvious after a LONG series of only-moves. Finding such moves is clearly out of scope for a hobby engine.

Build

Linux (default)

make linux          # release build
# Or directly:
cargo build --release

Binary: target/release/blunderchess

Windows (optional, via cross-compilation)

Uses cross and Docker to cross-compile a native Windows .exe from Linux.

Prerequisites (one-time):

cargo install cross                      # cross-compilation tool
sudo apt install docker.io               # required by cross
sudo systemctl enable --now docker
sudo usermod -aG docker $USER            # log out/in after

Build:

make windows

If you get permission denied on the Docker socket, either log out/in (to activate the docker group) or run:

sg docker -c "make windows"

Binary: target/x86_64-pc-windows-gnu/release/blunderchess.exe

ARM64 Linux (optional, via cross-compilation)

Same prerequisites as Windows above.

make arm

Binary: target/aarch64-unknown-linux-gnu/release/blunderchess

Runs on ARM64 Linux (Raspberry Pi 4/5, AWS Graviton) and on Android via Termux (Snapdragon Elite, MediaTek Dimensity, etc.).

Android ARM64 (optional, via cross-compilation)

Same prerequisites as Windows above.

make android-arm64

Binary: target/aarch64-linux-android/release/blunderchess

Native Android binary (NDK). No Termux needed — runs directly on Android devices.

Dev build

cargo build                              # debug, faster compile

Test

cargo test --lib                    # unit tests (fast)
cargo test --test benchmarks        # integration tests
cargo test --lib --test benchmarks  # all tests

Run

Paste the binary path into your GUI (Arena, CuteChess, Nibbler) as a UCI engine.

Or pipe commands directly:

echo -e "position startpos\ngo depth 8\nquit" | target/release/blunderchess

Key options

setoption name Hash value 64        # MB (default 64)
setoption name Threads value 4      # CPU threads
setoption name MultiPV value 3      # multi-PV analysis
setoption name OwnBook value true
setoption name BookFile value /path/to/book.bin