♟️ Chess Analysis

Offline-first chess analysis for Windows. Native UCI engines, an offline opening explorer, authentic move sounds, and a fast keyboard-driven UI.

Native UCI engines run as local child processes (no WebAssembly). The board mirrors the look and feel of a Lichess analysis board using Chessground, with a self-contained piece set and CSS board theme; no external branding or image assets are bundled or fetched. Everything, including the opening explorer and move sounds, works with no network connection.

Features

• Interactive board with legal-move highlighting, last-move & check markers, and a promotion picker. Right-click arrows and highlights for annotation.
• Variation tree: play a move from any earlier position to fork a line. Variations render inline in parentheses (Lichess/chess.com style); right-click a move to promote to main line or delete the sub-line.
• Opening explorer (offline): names the current opening with its ECO code and lists the known book continuations (main lines first) that you can click to walk theory. Backed by ~3,800 named lines from the Lichess chess-openings dataset.
• Move sounds: authentic wooden move/capture samples plus distinct cues for castle, promotion, check, and game end. Toggleable and persisted.
• Evaluation bar (White-oriented, logistic scaling), scaling with the board.
• Infinite analysis with MultiPV (1–10 lines) and clickable principal variations.
• Live engine statistics: depth/seldepth, nodes, NPS, hash usage, TB hits, time.
• Load any UCI .exe; options are auto-detected via the UCI handshake and saved. Per-engine option editor; configurations persist to userData/engines.json.
• Quick engine switch (Shift+E) that hops to your last-used engine and preserves the running/standby state.
• PGN and FEN import/export (paste, open file, copy, save file).
• Responsive layout that stays usable as the window shrinks, with a searchable keyboard-shortcut overlay (?).

Live analysis

Point the app at any UCI engine (here Stockfish 18) and get infinite analysis with MultiPV lines, principal variations, a live evaluation bar, a best-move arrow on the board, and search statistics (depth, nodes, NPS, hash, time).

Keyboard shortcuts

Press ? in the app for the full, always-current list.

Key	Action
← / →	Previous / next move
↑ / Home · ↓ / End	Jump to start / end
Ctrl+Z · Ctrl+Shift+Z	Undo / redo move
Delete	Delete the current move and its sub-line
F	Flip board
Space	Start / stop analysis
+ / −	More / fewer engine lines
E	Manage engines
Shift+E	Switch to last engine & analyze
M	Mute / unmute sounds
?	Show shortcuts overlay
Esc	Close dialogs

Getting started

npm install
npm run dev             # launch in development with HMR
npm run build           # production bundle to out/
npm run typecheck       # strict type-check (node + web)

npm run dist            # unpacked Windows build (release/win-unpacked/)
npm run dist:portable   # single portable .exe (release/ChessAnalysis-<ver>-portable.exe)
npm run dist:installer  # NSIS installer (release/ChessAnalysis-<ver>-setup.exe)

npm run icons           # regenerate build/icon.png + build/icon.ico from build/icon.svg
npm run build:openings  # regenerate the offline opening book from scripts/data/openings/*.tsv

The portable build is a single self-contained .exe: no install, just run it.

Note: if you launch Electron from a shell that has ELECTRON_RUN_AS_NODE=1 set, unset it first (npm run dev will otherwise crash with a whenReady error, because the Electron binary runs as plain Node).

Adding an engine

1. Click ⚙ Engines in the toolbar (or press E).
2. + Add engine, then pick a UCI executable (e.g. stockfish.exe).
3. The app performs the uci handshake, reads the engine name/author and options, and saves the configuration. Adjust options (Threads, Hash, etc.) inline; changes apply live during analysis and are persisted.

Appearance

• Board themes (Brown / Blue / Green) and piece sets (Cburnett / Merida / Alpha) are selectable from the top bar and persist across sessions. All pieces are freely licensed and bundled locally.
• The app icon is generated from build/icon.svg via npm run icons.

Architecture

Concerns are split into independent modules; no source file exceeds 300 lines.

src/
  shared/            IPC contract & engine types shared by all processes
  main/
    engine/          UciEngine (process + protocol), EngineManager, uciParser
    store/           configStore (persistence)
    ipc/             registerHandlers (IPC surface)
    index.ts         window lifecycle + hardened webPreferences
  preload/           contextBridge (the only renderer to main channel)
  renderer/src/
    chess/           ChessGame (chess.js wrapper), openings lookup, evaluation, pv
    audio/           procedural + sampled move sounds (Web Audio)
    state/           gameStore, engineStore, settingsStore, uiStore (Zustand)
    components/      board, eval, moves, engine, opening, toolbar, common
    hooks/           keyboard nav, analysis position sync, sound effects
    assets/          piece sets, move sounds, precompiled opening book
scripts/             icon generation, opening-book build (+ source TSVs)

Security: contextIsolation on, nodeIntegration off, a strict CSP, external links opened in the OS browser, and in-app navigation blocked. The renderer reaches the OS/engine only through the typed window.api bridge.

Notes

• The game model is a move tree (ChessGame): each position node keeps an ordered list of children, where children[0] is the main line and the rest are variations. PGN export/import round-trips variations as nested (...) (RAV).
• Engine scores are reported from the side-to-move and converted to White's perspective for the eval bar and line labels.
• The opening book is precompiled to a compact position-keyed JSON at build time and bundled as a string, so lookups are instant and require no runtime I/O.

Credits & data

• Opening data: lichess-org/chess-openings, compiled into src/renderer/src/assets/openings.json by scripts/build-openings.mjs.
• Move sounds: the "wooden piece" samples from the open-source Lichess project.
• Board & pieces: Chessground with freely licensed piece sets, rendered locally.
• Engine: bring your own UCI engine (e.g. Stockfish).

These third-party assets remain under their respective licenses.

License

MIT © 2026 Abhirup