A Windows desktop app for importing, filtering and playing the Lichess puzzle database offline. Part of the Jupiter family.
Version 3.2.0 adds optional short-mate screening and fixed rating ranges. The app imports, filters and plays puzzles, with players and Glicko-2 ratings, history, presets, export, an evaluation engine and a per-user installer. Local database discovery and user-managed downloads remain available. See the release notes and screening design and validation.
Download the Windows installer.
- Project brief: decisions, source data, workflows, measurements and open questions
- Workbench layout: regions, menus, states and keyboard behaviour for the desktop shell
- Source map: related folders and their dispositions
- Jupiter style exceptions: recorded departures from the style standard
Follows Jupiter style standard 1.1 through the shared Jupiter.UI library, which must sit beside this repository to build. The release's source.zip includes both folders and a SHA256 source manifest.
The rebuild and predecessor histories are both retained in this repository. The older Lichess Puzzle Desktop installation and its %LOCALAPPDATA%\LichessPuzzleDesktop data stay separate; 3.0 does not migrate that data. Existing Jupiter Lichess Puzzles installations upgrade in place and keep their data.
Install with dist/LichessPuzzles-<version>-win-x64-setup.exe. It installs for your Windows account without an administrator prompt, adds Lichess Puzzles to Start, and can be removed from Settings > Apps > Installed apps; puzzles, players and history are kept. The installer is not signed, so SmartScreen may ask you to confirm. Alternatively run LichessPuzzles.exe from dist/LichessPuzzles or the zip. Windows 11 24H2 or newer, x64; no separate runtime installation is needed.
Download the puzzle database from Lichess whenever you choose, then use File > Import puzzle file… to select your .csv or .csv.zst. With no readable store installed, the app automatically imports lichess_db_puzzle.csv.zst or lichess_db_puzzle.csv found beside the executable, in the data folder, or in its legacy source subfolder (in that order). It builds the offline store and keeps your original file; no download record is required. An existing store stays in use until you explicitly import an updated file. File > Get puzzle database from Lichess… opens the download page in your browser. The desktop app does not download files or check for updates itself; the CLI download commands remain available.
Filters apply as they change and can be saved as presets. Next puzzle (Ctrl+N) draws a matching puzzle at random or near your rating, optionally skipping puzzles you have played. Help > Keyboard shortcuts lists the keys. The window layout is described in docs/workbench-layout.md.
Near my rating keeps the target inside your chosen ±75, ±150 or ±300 range, with an optional difficulty offset. An empty selection asks you to change the range or filters; it never broadens them automatically. New settings default to near-rating selection at ±150 and skipping played puzzles; upgrades preserve saved choices.
Short-mate screening can exclude proven mate in one, or mate in one or two. It checks the position the solver sees, including every legal defence, before opening it. Screening is off until you choose it, and is saved with filter presets. Counts in the filter pane are before screening and rating matching. The app prepares a candidate in the background and rechecks its eligibility before use. Searches have a budget; an unfinished check does not mean the puzzle is difficult. If a batch produces no accepted puzzle, Next can be retried or the selection changed.
The original CSV, puzzle store and puzzle ratings are not edited by screening. Its reusable results live in screening.sqlite beside the player database, keyed by the full solver position and algorithm version. The file can be removed while the app is closed to rebuild the cache. Directly opening a puzzle by ID and exporting filtered puzzles still use the full database without applying this presentation-only screening.
Skip shallow engine solutions adds an optional second opinion from the app's small Rust engine. It searches each solver turn independently, then skips only complete reviews that consistently agree with every recorded solver move across all observed depths (at least two per turn). Different recommendations and incomplete reviews remain available. This experimental search-effort filter is off by default and saved with presets; it does not assign a human difficulty rating. Its disposable cache is engine-review.sqlite. See engine review for limits, measurements and interpretation.
Each player has a Glicko-2 puzzle rating starting at 1500 ± 350; a ? marks it provisional while the deviation is above 110. With Rated on, your first attempt at a puzzle is a game against it, using its rating and deviation from the database. The first wrong move, hint or solution makes it a loss, and a solve without them a win. Leaving a puzzle after playing in it counts as a loss. Replays are not rated. History lists every attempt.
This is a local rating based on your selected puzzles, not a Lichess account rating or over-the-board rating. Short-mate detection describes a position, not its human difficulty; a short mate can still be challenging. Screening and background preparation never count as attempts.
The Player rating section stays at the top of both Puzzle and History, with the current player, rating, provisional status, rating deviation and rated-puzzle count. If Next would abandon an attempt, matching uses the rating that its loss would produce. The loss is committed only when an eligible next puzzle is ready. Selection retries if player, filter, session or database state changes before the new session starts.
Evaluation (off by default; View or Settings) runs a small built-in engine after the puzzle ends, or while solving if you choose. It shows a score, best line and an evaluation bar. It is a guide, not an authority.
Settings > Appearance > Theme offers Dark, Light, and Use Windows setting. The choice applies immediately to the main window, settings and dialogs, and is saved with the accent and board settings.
lichess-puzzles download download the database, resuming an interrupted download; skipped when current
lichess-puzzles check-update compare the downloaded file with the server's (one HEAD request)
lichess-puzzles build build the puzzle store from the download, or --input <file.csv|file.csv.zst>
lichess-puzzles status describe the store
lichess-puzzles count [filter] count matching puzzles
lichess-puzzles sample [filter] -n 10 [--seed N]
lichess-puzzles screen [filter] -n 100 [--seed N]
lichess-puzzles review [id] [filter] -n 100 [--seed N] [--json]
review every solver turn with the small engine; does not change selection or ratings
lichess-puzzles show <puzzle-id> one puzzle with its solution in SAN
lichess-puzzles themes [filter] matching puzzles per theme
lichess-puzzles openings [filter] matching puzzles per opening family
lichess-puzzles analyse [id] [filter] -n 20 --millis 1000
run the engine on one or more puzzles and report how often it finds the first move
Filters: --rating 1500-1800 (or 1500-, -1800), --max-rd N, --min-popularity N, --min-plays N, --theme T (any of those given), --all-themes T, --without-theme T, --opening TAG (family or variation, such as Sicilian_Defense), --solver white|black, --length 2-3 (moves the solver plays). Theme and opening options repeat.
Data lives in %LOCALAPPDATA%\Jupiter\LichessPuzzles (--data-dir to change):
source\lichess_db_puzzle.csv.zst the download
source\download.json ETag, Last-Modified and length of the completed download
source\lichess_db_puzzle.csv.zst.part an interrupted download, with its own .part.json record
puzzles.store the puzzle store
puzzles-next.store an update built beside the open store, until it replaces it
players.sqlite players, ratings and history
settings.json, ui.json the desktop app's settings, filters, presets, layout and puzzle in progress
LICHESS_PUZZLES_DATA_DIR points the desktop app at another folder.
One file, memory-mapped for reading and replaced only by renaming a completed build into place:
- Records: 32 bytes per puzzle, holding everything filters read: theme bitmask (128 bits), plays, rating, deviation, opening family and variation ids, popularity, move count and flags (solver side, daily puzzle).
- Ids: packed into a
u64each, in file order, with a sorted index only if the source is out of order. - Details: FEN, moves, game URL and daily date as text, in zstd-compressed blocks of 1,024 puzzles.
- Info: a JSON trailer with section offsets, theme and opening tables, the source file's version and any rows that were skipped.
Every puzzle is checked during the build: the FEN must parse and every move must be legal. Rows that fail are skipped and reported.
Requirements: Rust 1.99.1 (pinned in rust-toolchain.toml), .NET SDK 10.0.1xx (global.json), Visual Studio Build Tools with MSVC (including its x64 redistributable files) and the Windows 11 SDK, Windows 11 x64.
pwsh build/build.ps1This checks formatting, lints and tests the Rust workspace, runs the C# interop checks, publishes dist/LichessPuzzles and dist/LichessPuzzles-<version>-win-x64.zip (including the CLI), and compiles the installer with Inno Setup 6. It also writes a source archive containing the shared UI library, dependency licence notices and LichessPuzzles-<version>-SHA256SUMS.txt. Git is required for source packaging; Inno Setup 6 is required for the installer. -SkipChecks publishes only; -PortableOnly skips the installer.
core/domain Rust domain core: download, store, filters, session, service
core/ffi C ABI (lpz_*) over the service, protobuf messages from proto/puzzles.proto
cli lichess-puzzles command line
src/LichessPuzzles.Interop C# wrapper over the ABI
src/LichessPuzzles.App WinUI 3 shell
tests/LichessPuzzles.InteropTests checks across the real DLL boundary
build build script, native build targets, icon script
- Code: MIT, see
LICENSE. - Puzzles: the Lichess puzzle database, released under CC0.
- Chess rules: cozy-chess, MIT.
- Pieces: Merida by Armando Hernandez Marroquin, from lichess-org/lila, GPL version 2 or later. The editable SVG artwork, attribution and full licence ship in
Assets/pieces; the artwork retains its separate licence. - Dependency licences and copyright notices:
THIRD-PARTY-NOTICES.txtin the installed or portable folder. - Theme descriptions are written for this app.
- Evaluation: piece-square tables from Tomasz Michniewski's "simplified evaluation function".