Chess Solver

A desktop chess analysis tool powered by Stockfish 18.
Set up any board position and get the top engine-recommended moves with evaluations, tactical motifs, and principal variations.

Tactical motifs flagged on every line, here in Neon dark

Settings: theme, mode, think time, updates and About

_{Four themes, each in light and dark: Matte, Frutiger Aero, Neon and Neubrutalism}

Features

• Drag-and-drop piece movement with click-to-place editing
• Paste a FEN to load a position, and copy the current FEN
• Import a PGN game (file or paste), step through it, and export the current game
• Move list with back, forward, start, and end
• Stockfish 18 analysis on all your CPU cores (multi-threaded NNUE build), streaming results so the best move so far appears within milliseconds of each move
• 1 / 3 / 5 candidate lines (fewer lines = deeper search), with eval bars and depth info
• Adjustable think time per position (1s / 3s / 5s / 10s)
• Tactical motif detection (forks, pins, skewers, checks, etc.)
• Opening name recognition
• Checkmate, stalemate, and draw detection
• Four themes (Matte, the default; Frutiger Aero; Neon; Neubrutalism), each with light and dark. System (the default mode) follows your computer's setting live
• An original piece set and a themed board: squares, frame, coordinates, highlights and pieces restyle with each theme
• A wide layout that fills the window: the board grows with it, panels keep fixed heights and scroll inside, and nothing shifts as you play
• Board flip and turn switching
• Update check against GitHub releases: automatic at startup (a banner appears when a new version is out) and on demand from Settings → Check for updates

Checkers

A Checkers tab (top of the window) analyses American checkers / English draughts: captures are required, a jumping piece keeps jumping, and a man that reaches the far row is crowned (its move ends there).

• Ranked best moves with evaluations: +1.00 is about one piece ahead for the side to move, and "Win in 5" is a proven forced win. Click a line to play it.
• Set up any position with the piece row under the board, or paste position text in the PDN style (B:W21,22,K30:B1,2,K9).
• Play vs engine as Black or White, with optional hints, and Undo.
• Tour walks through the rules with live example positions.

The engine is written for this app and runs in a Web Worker: alpha-beta search with iterative deepening, a transposition table, killer and history move ordering, and a capture extension. Move generation is checked against the published perft counts (depth 1 to 8 from the start: 7, 49, 302, 1469, 7361, 36768, 179740, 845931). There are no endgame tables yet; small king endings are solved by search instead.

Quick Start (Development)

npm install
npm run dev

Opens the app in your browser at http://localhost:5173.

The Stockfish engine (stockfish-18.js + its ~113 MB .wasm) comes from the stockfish npm package: the dev server serves it straight from node_modules, and npm run build copies it into dist/. Nothing engine-related is committed to the repo.

Testing

npm test        # unit tests (vitest)
npm run lint    # eslint
npm run build   # type-check + production build

The same three steps run in CI on every push and pull request.

Web build (static hosting)

npm run build:web   # type-check, build dist/ for the web, check file sizes

The web build runs entirely in the browser and needs no server code, so any static host works (for example Cloudflare Pages with output directory dist). It differs from the desktop build in three ways:

• Engine: Stockfish 18 lite (about 7 MB) instead of the full 113 MB build, which is over the 25 MiB per-file limit of hosts like Cloudflare Pages. Lite is a little weaker but still very strong.
• Threads: public/_headers sends Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp, so the page gets SharedArrayBuffer and the multi-threaded lite engine. On a host that ignores _headers, the page falls back to the single-threaded lite engine: slower, but analysis still works.
• Updates: the update check links to what's new and suggests a reload instead of offering an installer.

scripts/check-dist.mjs runs after the build and fails if any file in dist/ is over 25 MiB. CI runs the web build too. If the engine can't start, the analysis panel says so: you can still set up positions and read games, and Retry reloads the page.

Download

Prebuilt binaries are on the releases page:

• Windows — Chess.Solver.Setup.<version>.exe, a per-user installer (no administrator rights required). Run it and the app is added to the Start Menu with a desktop shortcut (SmartScreen may warn on first run because the binary is unsigned; choose "More info → Run anyway").
• macOS — Chess.Solver-<version>-universal.dmg, a universal (Intel + Apple Silicon) disk image. The app is not notarized, so on first launch right-click the app → Open → Open to get past Gatekeeper.

Release binaries are built by the release workflow on tagged commits.

Build Standalone Desktop App

npm install
npm run electron

Builds the production bundle and launches it as a standalone Electron desktop app.

Build Installers

npm run dist

Builds for the platform you run it on and outputs to release/:

• On Windows: release/Chess Solver Setup <version>.exe — per-user NSIS installer — plus release/win-unpacked/, the unpacked app folder it installs from
• On macOS: release/Chess Solver-<version>-universal.dmg — universal disk image for Intel and Apple Silicon

.dmg files can only be built on macOS; CI's release workflow uses a macOS runner for that.

First-time build (Windows)

The first npm run dist on a machine downloads the winCodeSign toolchain, which contains symbolic links into a macOS subfolder. Windows blocks symlink creation unless one of these is true:

• The PowerShell session is running as Administrator, or
• Developer Mode is enabled in Settings → Privacy & Security → For developers

Run the first build under one of those conditions. Subsequent builds reuse the cached toolchain and do not need elevated privileges.

Install as a Desktop App (Windows)

npm run dist produces the installer itself — run release/Chess Solver Setup <version>.exe.

It installs per user into %LOCALAPPDATA%\Programs\Chess Solver (no administrator rights, no UAC prompt), creates desktop and Start Menu shortcuts, and registers an entry under Settings -> Apps so it can be uninstalled normally. Re-running a newer installer upgrades in place.

To pin to the taskbar, right-click the desktop shortcut -> Pin to taskbar (Windows blocks programmatic taskbar pinning).

Look and feel

Themes

Open Settings (the gear, top right) to pick a theme and a mode:

Theme	Feel
Matte (default)	Warm paper grain, a walnut board frame, small crafted corners with a hairline double edge
Frutiger Aero	Glossy glass panels over a sky backdrop, glossy pieces, soft top corners
Neon	Deep night surfaces, glowing cyan and violet edges, chamfered corners
Neubrutalism	Flat colour, thick outlines, hard offset shadows, square corners

Each theme has light and dark. Light, Dark or System; System is the default and follows the OS as it changes. Your choice is saved. ?skin=neon (or matte, aero, brutal) in the URL picks a theme for that visit.

Every colour, radius, shadow and corner is a CSS variable in src/theme/tokens.css; components never hard-code colours. The board squares, coordinates, highlight, frame and piece colours are tokens too, so the board restyles with the theme. Tests (src/theme/*.test.ts) check that all eight variants define every token and keep body text, muted text, links, evaluations, warnings, opening names and dropdowns at WCAG AA contrast or better, and that board coordinates and pieces stand out from their squares.

Board and pieces

The pieces are an original geometric set drawn for this app (src/components/pieceArt.ts), not a stock set. The same shapes are dressed per theme: ivory and ebony in Matte, glossy porcelain and navy in Aero, glowing outlines in Neon, and bold black outlines in Neubrutalism.

Layout

The board sizes itself to the window. The analysis list and the move list have fixed heights and scroll inside, the controls stay in place, and the page always reserves room for its scrollbar, so switching 1/3/5 lines, a long game or a warning never moves anything.

Title, logo and icons

The title is set in Bungee (SIL OFL), bundled in src/assets/fonts so it works offline and in the desktop app, and styled per theme. The logo, an isometric board with the app's knight and an orange solve arrow, is src/assets/logo.svg. It is also the favicon (public/favicon.svg), the app icons (public/icon-192.png, public/icon-512.png), the desktop icons (build/icon.ico for Windows, build/icon.png at 1024×1024 for macOS) and the social card (public/og-image.png). After editing the SVG, re-export the PNG and ICO sizes from it and rerun npm run dist.

How to Use

1. The board starts with the standard chess position. Stockfish begins analyzing automatically.
2. Select a piece from the row below the board, then click any square to place it.
3. Use Remove to erase pieces from the board.
4. Toggle White/Black to move to change the side to analyze.
5. The analysis panel shows the top engine moves with evaluations, tactical motifs, and principal variations. Use the 1 / 3 / 5 selector to trade breadth for depth.
6. Click any analysis line to play that move on the board.
7. Hover over a line to highlight the move on the board.
8. Use Reset to restore the starting position or Clear to empty the board.
9. Paste a FEN into the FEN field in the Position and game panel and press Load. Copy puts the current position on the clipboard. A FEN the board cannot represent shows an error and does not change the position.
10. Import PGN reads a .pgn file. Paste PGN does the same from text. The move list starts at the beginning of the game; use the arrows or click a move to step through it. Export PGN downloads the current game. Import keeps the main line.
11. Open Settings (the gear, top right) to pick a theme and light, dark or system mode, change the engine's think time, check for updates, or see the version under About. A dot on the gear and a banner under the header mean a new release is available.

How it's built

Chess Solver is an Electron desktop app. The window loads the React UI from a small static server in the main process (electron/main.cjs), bound to 127.0.0.1. Every response from that server sends Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp. Browsers only expose SharedArrayBuffer on a cross-origin-isolated page, and the multi-threaded Stockfish build needs it to start its pthread workers. Electron's window does not reliably apply those headers (crossOriginIsolated stays false), so the main process also enables SharedArrayBuffer with a Chromium command-line switch before the app is ready. The dev server sends the same two headers.

The engine is the Stockfish 18 multi-threaded NNUE build from the stockfish npm package. It is not committed to the repo. In development, Vite serves stockfish-18.js and stockfish-18.wasm from node_modules. The production build copies them into dist/ as stockfish.js and stockfish.wasm. The UI runs that script in a Web Worker (src/engine/stockfish.ts) and speaks UCI to it.

The board is React, drawn with react-chessboard using the app's own piece set and theme colours. Legal play goes through chess.js, which keeps castling rights, en passant, and the move counters. The piece editor is allowed to build positions a real game cannot reach, including ones chess.js refuses to load. Those edits go through the raw FEN helpers in src/engine/fen.ts.

Lost stops, and restarting a stuck search

Stockfish answers every go with exactly one bestmove. The worker queues a new go while the previous search is still unwinding, but it runs stop immediately. One stop can therefore arrive before the go it was meant to cancel, and that search continues with nothing waiting on it. The engine treats that as a lost stop: it sends stop again every 100ms until the matching bestmove arrives. If none arrives within 8 seconds, the worker is taken to be stuck, torn down, and started again. The position the user asked for is held in a pending slot and runs on the new worker, so a restart does not need a manual refresh. A second watchdog covers a go that never answers at all, and retries that search once before reporting failure. Rebuilding the worker recompiles the WASM binary (about 113 MB) and clears the hash table, so both timeouts wait longer than a healthy engine needs.

Why the Windows download got smaller

The v1.1.1 portable .exe was a 304 MB download. electron-builder was packing every Stockfish build shipped in node_modules next to the single copy in dist/ that the app actually loads. Excluding node_modules from the package, then switching Windows from a portable executable (it unpacked its whole payload on every launch) to a per-user NSIS installer, brought that download to about 165 MB. Those two figures are the ones recorded with that change.

Limitations and roadmap

• Windows and macOS builds are unsigned and not notarized, so SmartScreen and Gatekeeper warn on first launch.
• The editor can produce positions a game cannot reach. Analysis still runs when the board has one king of each color and eight ranks of eight squares. Tactic labels are omitted when chess.js rejects the FEN, which is what a pawn on the first or eighth rank does.
• PGN import follows the main line. Variations, comments, and annotations are dropped, and export writes that main line back out.
• Opening names come from a table of common positions in the app, not a full opening book.
• There is no online play and no engine-versus-engine mode.

Still to do: code signing and notarization, and PGN variations and comments.

Tech Stack

• React 19 + TypeScript
• Vite (dev server serves COOP/COEP headers so SharedArrayBuffer is available for the threaded Stockfish build)
• Stockfish 18 WASM (multi-threaded NNUE build, pthread workers), from the stockfish npm package
• chess.js for move validation
• react-chessboard for the board UI
• Electron for desktop runtime, electron-builder for packaging
• Vitest for unit tests, GitHub Actions for CI

License and credits

Chess Solver is free software under the GNU General Public License, version 3 only. See LICENSE.

The desktop app bundles Stockfish 18, which is itself under the GNU GPL version 3. An MIT license on this repository did not cover distributing that engine, so the project is GPL-3.0-only. THIRD_PARTY_NOTICES names the other components and their licenses.

The Stockfish developers write the engine: https://github.com/official-stockfish/Stockfish. The WebAssembly build comes from stockfish.js by Nathan Rugg (npm package stockfish): https://github.com/nmrugg/stockfish.js.

Packaged builds carry the GPL text, the third-party notices, and the Copying.txt from the stockfish package. They are placed in resources/licenses/ beside the app, and again under dist/licenses/ inside the app archive. The packager's !node_modules/**/* exclusion would otherwise omit the package's own license file; those copies are what replace it.

Source for this application: https://github.com/ccharafeddine/chess-solver