♟️ Kletka — Cross-Platform Chess Analyzer

Latest Release License: GPL v3 Platform

🌐 English · Русский · 中文

Website: https://andreykhrypach.github.io/Kletka/

Kletka is a cross-platform chess analysis tool that supports PGN files, variations, annotations, and the Stockfish engine. It features a modern, customizable interface and is available for Windows, Linux, and macOS.

⬇ Download GitHub Repo

📝 Changelog

See CHANGELOG.md for a detailed history of changes.

🚀 Features

📺 Video Tutorials

Step-by-step guides on our YouTube channel:

Windows:

Linux:

More tutorials coming soon — macOS.

📚 Opening Books (Polyglot)

Kletka supports Polyglot opening books (.bin files), allowing you to explore and study chess openings interactively — and to build your own repertoire.

How to use opening books:

  1. Go to Books → Load Book
  2. Select a Polyglot book file (.bin)
  3. Navigate through variations using the keyboard:
    • ↑ / ↓ — move between variations
    • → / Enter — select a variation
    • ← — go back to the previous position

How to edit a book:

Kletka allows you to add moves directly to the loaded book:

Export game tree to Polyglot book:

You can export your current analysis tree as a Polyglot book:

  1. Analyse or set up a position with variations
  2. Go to Books → Export to Polyglot Book…
  3. Choose a folder and filename — the book is created in .bin format

All moves from the tree (main line + all variations) go into the book. Transpositions and duplicates are automatically deduplicated.

The resulting book can be loaded back into Kletka or used with Stockfish, Leela, ChessBase, Scid, Arena, and other compatible software.

System Requirements for Books

For opening book functionality, Kletka requires:

--add-opens java.base/sun.nio.ch=ALL-UNNAMED
--add-opens java.base/sun.misc=ALL-UNNAMED

Note: If you're running Kletka from the command line, use:

java --add-opens java.base/sun.nio.ch=ALL-UNNAMED \
--add-opens java.base/sun.misc=ALL-UNNAMED \
-jar Kletka.jar

These arguments are required for fast Polyglot book operations using memory-mapped files.

🔧 Technical Details: Memory-Mapped Files

Kletka uses memory-mapped files (MappedByteBuffer) for lightning-fast Polyglot book operations, even on HDD.

Important: Mapped byte buffer is not released by the JVM garbage collector while a reference exists. So that you can delete, move, or replace a book file while Kletka is running, the application explicitly calls: 
sun.misc.Unsafe.invokeCleaner(mappedByteBuffer);

This immediately releases the OS-level file lock.

What this means for you:

Linux: Known Issues

On Debian Trixie / Ubuntu 24.04+ with Wayland, dialogs may not receive focus (keyboard works, mouse doesn't). This is a known JavaFX 17 + GTK 3 + Wayland bug.

Solution: already included in Kletka — the app runs with -Djdk.gtk.version=2, which uses GTK 2 via XWayland.

Recommended books:

For best results, we recommend using the uho-pohl.bin opening book, which contains extensive high-quality opening variations.

Where to get Polyglot books:

You can download free opening books from the official Polyglot books repository: 🔗 Polyglot Books Repository

Other popular sources:

📋 Copy Position (FEN + ASCII)

You can copy the current position to the clipboard in a convenient format — FEN plus an ASCII diagram:

This is useful for:

The output includes the FEN on the first line and an ASCII diagram below it, wrapped in a Markdown code block for easy pasting.

🐛 Known Issues on macOS

Drag-and-drop: piece is grabbed by the corner

Symptoms:

Cause: Known JavaFX bug JDK-8333919 — dragViewOffsetX/Y are ignored on macOS.

Fix: Fixed in JavaFX 23 (requires JDK 21+). Kletka currently uses Java 17 + JavaFX 17.

Workaround:

Status: Tracked in issue #XXX. Will be fixed when we migrate to the new stack.

🖥️ Screenshots

Quick Preview

Main interface PGN browser
Main interface PGN browser
Open Polyglot Book Polyglot Book Loaded
Open Polyglot Book Polyglot Book Loaded

Full Size

Click on an image to open it in full size in a new tab.

Main interface

PGN browser

Open Polyglot Book

Polyglot Book Loaded

📦 Installation

Windows

Download Kletka.exe from the Releases page and run the installer.

macOS

Download Kletka.dmg, open it, and drag Kletka.app to the Applications folder.

Linux (Debian/Ubuntu)

sudo dpkg -i kletka*.deb

🛠️ Building from Source

Prerequisites

Important JVM Arguments for Development

When running from your IDE, add these VM options:

--add-opens java.base/sun.nio.ch=ALL-UNNAMED
--add-opens java.base/sun.misc=ALL-UNNAMED

This ensures full Polyglot book support during development.

git clone https://github.com/AndreyKhrypach/Kletka.git
cd Kletka
mvn clean package

Platform-specific builds

# Windows
mvn clean package -P windows

# Linux
mvn clean package -P linux

# macOS
mvn clean package -P mac

🧠 Setting up Stockfish

Kletka uses the Stockfish UCI engine for analysis. You need to install it separately:

Windows

  1. Download Stockfish from the official website: https://stockfishchess.org/download/
  2. Extract the archive
  3. In Kletka, go to Engine → Configure Engine and select the stockfish.exe file

Linux (Debian/Ubuntu)

sudo apt install stockfish

Then in Kletka, go to Engine → Configure Engine and select the stockfish binary.

macOS

brew install stockfish

Then in Kletka, go to Engine → Configure Engine and select the stockfish binary.

📄 License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

👨‍💻 Author

Andrey Khrypach

⭐ Support

If you like this project, please ⭐ it on GitHub!