Skip to content
Projects

OTAKUWeBer/ChessPilot has 37 GitHub stars and 7 forks. GitHot measured +1 stars in 24 hours. Last checked 2026-11-15 15:03 UTC. Last push 2026-11-12.

How these counts are measured

37 stars7 Forks +1 in 24h

What you can do

  • 100% Offline — all detection & analysis run locally.
  • Automatic Stockfish Download (CPU-Optimized) — ChessPilot automatically detects your CPU features (AVX2, AVX512, POPCNT, etc.) and downloads the most optimized Stockfish build on first run.
  • FEN Extraction — ONNX-based piece detector (Zai-Kun’s model).
  • Stockfish Analysis — instant best-move suggestions.

Measured star growth

in 24h
+1
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Introducing an advanced chess bot that automates gameplay on 2D on-screen chess boards, delivering a seamless and immersive experience.

Productivity

README.md

Original

ChessPilot Logo


ChessPilot — v2.x

A fully offline chess position evaluator and autoplayer for Windows and Linux — powered by ONNX and Stockfish.


A lightweight, privacy-first tool that reads a **2D on-screen chess board** (Chess.com, Lichess, WorldChess, etc.), evaluates the position locally with Stockfish, and (optionally) plays the best move automatically.


🎥 Demo Video


🎉 Highlights (What's New)

v2.3.0 — Architectural Modularization, Reliability & Quality

  • Modular Subsystem Separation — Refactored the monolithic downloader into focused, decoupled modules: cpu_features.py, download_dialog.py, and downloader.py.
  • Pure Core Domain & Perception Service — Extracted desktop screen capture and ONNX board inference out of core/ into a dedicated perception service (board_reader.py), keeping the core domain purely mathematical and free of I/O.
  • Automated Unit & Integration Test Suite — Added a 25-test automated test suite covering live Stockfish UCI communication, archive extraction, coordinate notation, FEN serialization, and move validation (python -m unittest discover tests -v).
  • Hardened Exception Architecture — 100% of bare try-except-pass blocks eliminated across the codebase; replaced with strictly typed exceptions and structured debug logging (CodeFactor A+ grade).
  • Safe Extraction for Modern Python — Added filter='data' archive extraction support, ensuring complete forward compatibility with Python 3.12, 3.13, and 3.14.
  • Centralized Detection Constants — Unified piece class IDs and detection mappings into model_classes.py.

v2.2.1 — Production Stability, Automation & Performance

  • Universal Move Automation — Added intermediate drag-and-drop movement events on Windows for seamless recognition on Chromium-based browsers (Chess.com, Lichess).
  • Smart Auto-Castling Detection — Automatically detects when online platforms move the rook upon king castling, preventing redundant clicks or lingering selections.
  • Streamlined Pawn Promotion — Eliminated redundant inference overhead during promotions; fully compatible with platform auto-queen settings.
  • Thread-Safe UI Operations — All background loop and move executor UI state transitions are strictly dispatched through the Qt main event loop (QTimer.singleShot), guaranteeing zero thread-affinity conflicts or UI freezes.
  • Optimized CPU & Logging — Replaced high-frequency screenshot log spam with debug-level telemetry to minimize disk I/O and CPU overhead during auto-play.
  • Overlapping Detection Precision — Piece recognition resolves overlapping bounding boxes using square-level confidence grids.

v2.2.0 — The Architecture & Aesthetics Update

  • Massive Structural Refactor — The monolithic executor module has been split into clean core, game, and utils domains, improving performance and maintainability.
  • Bulletproof Engine Stability — Prevented Stockfish from hanging infinitely (the "stuck analyzing" bug) by adding precise timeouts, and added safe Ctrl+C interrupt handlers to end the process cleanly without core dumping.
  • Gorgeous UI Modernization — Replaced mismatched styles with a cohesive "Emerald and Slate" dark theme managed through a centralized Styles class.
  • Linux Patches — Fixed Wayland cursor tracking and pawn promotion screenshot captures.

v2.1.0 — Stability, Precision & Performance

  • Full pawn promotion support — handled automatically and reliably.
  • Small under-the-hood improvements for cross-platform stability.

v2.0.0 — PyQt6 UI (Polished)

  • Brand-new PyQt6-based frontend (replaces old Tkinter UI).
  • Same workflow and shortcuts — just smoother and more stable.

⚡ Features

  • 100% Offline — all detection & analysis run locally.
  • Automatic Stockfish Download (CPU-Optimized) — ChessPilot automatically detects your CPU features (AVX2, AVX512, POPCNT, etc.) and downloads the most optimized Stockfish build on first run.
  • FEN Extraction — ONNX-based piece detector (Zai-Kun’s model).
  • Stockfish Analysis — instant best-move suggestions.
  • Auto Move Execution — applies engine moves to the GUI board.
  • Manual Play — use Play Next Move to control timing.
  • Automatic Promotion — follows Stockfish’s preferred choice.
  • Castling Rights & Depth Control — flexible configuration.
  • Retry Logic — failed moves automatically retried up to 3 times.
  • Cross-Platform — AppImage/DEB for Linux, EXE for Windows.

📦 Download

👉 Download the latest release

The ONNX model (chess_detectionv0.0.4.onnx) is included inside all official AppImage, EXE, and DEB builds.


🔒 Windows Antivirus Warnings (False Positives)

Windows may flag unsigned executables — this is common for small open-source projects.

If you see a warning:

  1. Verify the release on GitHub.
  2. Scan the binary on VirusTotal.
  3. Build from source (python src/main.py) for maximum safety.
  4. Only run if comfortable — or use a VM.

🛠️ Engine Configuration (engine_config.txt)

Place this file next to the executable to customize Stockfish:

# ChessPilot Engine Configuration

# Memory in MB (64–1024 recommended)
setoption name Hash value 512

# Number of CPU threads
setoption name Threads value 2

Restart ChessPilot after editing.


⚙️ Prerequisites (From Source)

PyQt6 is required for the UI.

Related Links


Linux

Install system dependencies:

# Ubuntu / Debian
sudo apt install python3-pyqt6        

# Arch Linux
sudo pacman -S python-pyqt6

# Fedora
sudo dnf install python3-qt6

Wayland Users (Arch Linux only)

If you are running Wayland instead of X11, install the following:

sudo pacman -S wayland-utils

Install Python dependencies:

pip install -r requirements.txt

Make sure your Python virtual environment is activated if you are using one.

Windows

pip install -r requirements.txt

If you see errors about missing vcruntime or msvcp DLLs, install the latest VC++ Redistributable - here.


▶️ Run (From Source)

git clone https://github.com/OTAKUWeBer/ChessPilot.git
cd ChessPilot
pip install -r requirements.txt
python src/main.py

Workflow

  1. Choose White or Black.
  2. Set castling rights if needed.
  3. Adjust analysis depth.
  4. Pick Manual or Auto mode.
  5. (Press ESC to reopen color selection.)

Running Tests

To run the automated test suite:

python -m unittest discover tests -v

✅ Platform Support

  • Windows — tested, EXE provided
  • Linux — tested, AppImage & DEB provided (Wayland supported)
  • macOS — not yet supported (looking for contributors)

🔁 Troubleshooting & FAQ

Board detection is incorrect → Move the ChessPilot UI aside so the detector has a clear view of the board. → Ensure the board is 2D and unobstructed.

Offline Setup / Stockfish didn’t download → ChessPilot is 100% offline-ready. If you have no internet access or automatic download fails, simply place your stockfish (or stockfish.exe) binary and chess_detection.onnx next to the ChessPilot executable (or in the src/ directory when running from source). → System-installed Stockfish from your PATH is also automatically detected on Linux.

Where to find logs → Click "⌨ Shortcuts" in the app and select "Open Logs Folder" (or press L). → Or open manually:

  • Windows: %LOCALAPPDATA%\ChessPilot\logs\chesspilot.log
  • Linux: ~/.local/share/chesspilot/logs/chesspilot.log (or $XDG_STATE_HOME/chesspilot/logs)

How to report an issue When opening an issue on GitHub, please make sure to include:

  1. Operating System & Display Server: (e.g. Windows 11, or Ubuntu 24.04 Wayland/X11).
  2. Installation Method: (Pre-built Windows .exe, Linux AppImage/DEB, or from source).
  3. Log File (chesspilot.log): Include relevant log output (or attach the file).
  4. Chess Platform & Browser: (e.g. Chess.com on Google Chrome, Lichess on Firefox).
  5. Screenshots / Video: If board detection fails, attach a screenshot of the chessboard as shown on your display.

🤝 Contributing

PRs and issues are welcome.

Areas that need help:

  • macOS packaging
  • UI/UX enhancements

📜 License

This project is under the MIT License.


🙏 Acknowledgments

Project & Dependencies

  • Zai-Kun — ONNX 2D chess piece detector
  • Stockfish Team — world-class chess engine
  • Microsoft VC++ Runtime
  • All contributors and testers