Cute Chess runs engine matches and gives you the same code as a library

One codebase, three ways to reach it

Cute Chess is described as a graphical user interface, command-line interface and a library for playing chess, written in C++ using the Qt framework. The interesting thing about the project is not any one of those three, it is that they share the same core.

The graphical program is cutechess, and it can be run from a command line or from the desktop environment's application launcher. The command-line program is cutechess-cli, and its stated job is playing games between chess engines, which is what makes it a tool for engine developers rather than for players. The library form lets you take the engine-match machinery into your own program.

That last option is the one that distinguishes the project from a chess GUI with a scripting console. If you want to run a batch of engine pairings, apply a time control, collect the results and report them, the library is the piece that goes into your tool, and the CLI is the reference implementation of how that tool is meant to drive it.

The project was written by Ilari Pihlajisto and Arto Jonsson together with a wider group of contributors, and it is developed in the open with a CHANGELOG.md, an AUTHORS file and a TODO in the repository root. The last push to the master branch was on 2026-09-01, and the repository is not archived.

How the command line runs a match

The example in the README is the whole interface in one line, and it is worth reading slowly because the vocabulary is the documentation.

To play ten games between two Sloppy engines, assuming sloppy is in PATH, with a time control of 40 moves in 60 seconds:

$ cutechess-cli -engine cmd=sloppy -engine cmd=sloppy -each proto=xboard tc=40/60 -rounds 10

Each part has a job. -engine is repeated, once per engine, and each one takes a command specification, here cmd=sloppy, which is the engine binary the tool launches. -each applies settings to every game, and the settings are given as a comma separated list of key and value pairs: proto=xboard selects the protocol the engine speaks, and tc=40/60 is the time control, 40 moves in 60 seconds. -rounds sets how many games to play.

The comma separated key=value convention for options is what makes the tool scriptable. A match is described entirely on the command line, so a regression suite can be a shell script, and a queue of tests can be a file of command lines. There is no configuration format to learn and no state to keep between runs.

The README points to cutechess-cli -help for descriptions of the supported options, and to the manuals for the full documentation, and the manuals are part of the documentation set in the docs directory. Since the option list is long, that help output is the reference to work from, and the wiki has the per-OS build instructions if you are compiling rather than installing a binary.

Building with Qt 6.8, CMake and a C++17 compiler

The build requirements are stated in one sentence and they are specific: Cute Chess requires Qt 6.8 or greater, a compiler with C++17 support and cmake.

The commands are the standard CMake pair:

cmake -S . -B build
cmake --build build

The project also lists the Qt modules it depends on, which tells you what a minimal build needs: qt-widgets for the interface, qt-svg for the board pieces, qt-concurrent for the background work of running engines, and qt-printsupport for printing. A fifth, qt-testlib, is optional and only needed for the unit tests.

That last entry is a useful signal about the project's structure. A library that lists its test dependency separately is one where the unit tests are part of the build rather than an afterthought, and where you can build the application without pulling in the test framework.

For binaries rather than a build, the README points at the Releases page. The documentation is available as plain-text, HTML and Unix manual pages in the docs directory, so the same material is readable in a terminal, in a browser, or through man, and per-OS build instructions live on the Building from source wiki page.

The repository also carries a .clang-format configuration and a CMakeLists.txt at the top level, which is the usual sign of a project with a defined code style.

The repository layout and what lives in each directory

The top level of the repository is small and tells you the shape of the project: projects for the source, dist for packaging, tools for helper scripts, translations for the localisation files, docs for the manuals, release-tool for the release machinery, a .builds directory for continuous integration configuration, and a .version file alongside the CHANGELOG, the AUTHORS file, the TODO, the COPYING file and the CMakeLists.txt.

The projects directory is where the three faces of the application come from, and the licence note in the README points into it: the components under projects/lib/components and those under projects/gui/components are the MIT licensed parts, while the rest of the project is GPLv3+.

That split is worth understanding rather than skipping. A library that other programs link against, and the components of a graphical interface, are the parts most likely to be reused in a proprietary or differently licensed product, and those are the parts the author chose to dedicate under MIT. The application around them stays under GPLv3+. That is a deliberate and common arrangement, and it is why a directory path is worth reading before you copy code out of the tree.

The translations directory is also a signal about the project's audience. A chess GUI that ships localisation files is a project that expects to be used by people who do not read English, which is a reasonable assumption for a tool that competes with free chess software downloaded from the internet.

Which face do you actually need

The three forms are not equally useful, and picking the wrong one is the most common mistake with a project like this.

The GUI is for a human at a keyboard. The cutechess program gives you a board, an engine, and a way to watch and control the game, with the pieces and the interface drawn by Qt and the engines running underneath. It is the part of the project that most users will recognise.

The CLI is for machines. It does not draw a board, it does not wait for a person, and it does not care which engine is stronger. It starts an engine, tells it to play, applies the time control, repeats the pairing the number of times you asked for, and reports the results. Every option is on the command line, which means a match suite is a script.

The library is for people who need neither of those exactly. It is the same machinery without the front end, so you can build your own tool: an engine regression harness that also uploads games somewhere, a tournament manager with a database behind it, a test that plays a specific position and checks the move. The README presents the library as one of the three products rather than an afterthought.

The practical consequence is that the interesting choice for most engineers is between the CLI and the library, and it is a choice about where the logic lives. If your needs are a match, a report and a return code, the CLI is already that, and using it directly means one fewer thing to maintain. If you need to compute something from the games, the library is the place to start.

What the CLI does not give you is a place to watch. For a human trying to understand why an engine lost a game, the GUI is the tool, and the CLI output is not a substitute for it.

Editorial conclusion

Adopt Cute Chess when you need to run repeatable matches between chess engines and want the same code available as a window, a command line tool and a library you can embed. Do not adopt it merely to play a game against an engine on a desktop, where the graphical client is the only part you need, and do not assume the whole tree is permissively licensed, because the component directories under projects are MIT while everything else is GPLv3+. Before you build, read the COPYING file and the per-component licence notices, run cutechess-cli -help to see how much of the match control is exposed, and check the CHANGELOG.md, because the 1.5.0 and 1.5.1 releases landed on the same day in June 2026.

Frequently asked questions

Official sources

1. cutechess/cutechess on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases