Jacobi: Fairy Chess Helpgame Solver

by François Labelle

Launch the latest version


Jacobi is a program to solve fairy chess proof game problems. Here's an example:

Dirk Borst
Nunspeet 2005
2nd place
r n b q . b n r
p p p k . p p p
. . B . . . . .
. . . . p . . .
. . . . . . . .
. . . P N N r .
P P P . . P P P
R . B Q . R K .
Proof game in 9.5 moves   (15+16)
Circe Rex Inclusive

The solution is 1.g3 d5 2.Bg2 d4 3.Bc6+ Kd7 4.Sf3 d3 5.O-O dxe2 6.d3 exf1=R [+wRh1] 7.Sbd2 Rxg1 [+wKe1]+ 8.Sf1 Rxg3 [+wPg2] 9.Se3 e5 10.O-O.

Jacobi solves this in a few minutes:

Jacobi can also solve some ordinary help stipulations but there is very little reason to do that because Jacobi shouldn't be faster than Popeye or WinChloe which support more stipulations, fairy conditions, and fairy pieces.

It can also solve orthodox proof games, but there is very little reason to do that because Jacobi should be slower than Natch or Euclide which are optimized for the orthodox case.

It cannot solve stipulations containing defensive moves, like directmates or selfmate, which is why the subtitle calls it a "helpgame solver". As an exception, Jacobi will accept one defensive halfmove at the very end of the problem.

Jacobi's strengths:

Entering problems

For now, Jacobi only supports entering problems in a text format similar to Popeye's. Eventually I plan to add a graphical editor, but the text format is still useful to make it possible to keep track of problems in a text file, or to easily exchange problems with others in a forum or by e-mail.

Here are some examples.

Proof games

Special proof games

Chaining multiple stipulations together

Reflex stipulations

Defensive moves

Jacobi will accept a defensive move if the situation being defended against can be directly tested. So a s#1 is fine because Black is defending against checkmate, but a s#2 is not, because the first black move is defending against a s#1, which is not an instant verification.

This means that Jacobi can handle stipulations where the only defensive move is at the very end of the problem, but it can also handle some other cases too. The stipulation hsx5 followed by the stipulation hs#2 works, but it requires elaboration. Black's 5th move is defensive in the sense that Black will avoid capturing if he can, but Black's choice among possible capturing moves will be helpful.

PG demolition mode

The solver option "PG demolition mode" searches the most likely moves first and then progressively tries less likely moves in multiple passes. It should find a cook faster if there is one. On the other hand, if the problem is sound then it will take much longer to prove it, so you should not use the option if you expect the problem to be sound. Many people ask me how many passes it makes but there's no easy way to answer that. It is best to imagine that this mode takes infinite time, so you stop it when your patience runs out.

The option is for proof games only. If the problem doesn't have a proof game component ("dia" or equivalent), then there will be just one pass which will be identical to a search with the option off. If the solver is doing more than one pass then the option is working. The option is famous for having been able to cook JF-1146 in less than 1 hour.

stipulation dia16.5 forsyth r1Bs1rs1/ppP1k2p/7b/8/p7/3K1S1r/1P5P/3S2R1
condition Masand


The solver runs quickly in recent versions of Firefox and Chrome. One exception is Internet Explorer which is from 3x to 20x slower than the competition, even with IE 11. Its successor, Edge, is supposed to be faster.

As a way to test your performance, the first example (listing solutions to Fool's mate) should take about 0.2s on a reasonable machine.

If you get poor performance, you could consider installing a second browser (different from your favorite one) that you'd use only for running Jacobi.


Jacobi uses a transposition table with hash keys of 86 bits, which gives a theoretically very tiny chance of missing a solution. Jacobi may also contain bugs, which is a more likely source of incorrect results. If you believe that Jacobi returned a wrong result for a problem, then please tell me by e-mail.

Keep in mind that fairy conditions are not always perfectly defined, especially in the way they interact when a problem uses more than one. My goal is to copy the behavior of the latest version of Popeye so that a problem that is C+ in Popeye will be C+ in Jacobi, and vice-versa. If you find a difference in behavior which is not a bug in Popeye, then tell me and I'll try to match what Popeye does.

Shorter solutions

Currently, Jacobi only searches for solutions of the exact specified length, as if each stipulation had the "exact-" prefix in Popeye. Solvers are divided on this issue, with Popeye and WinChloe reporting shorter solutions, but not Natch and Euclide. I plan to add a way to automatically search for shorter solutions, and maybe make it the default.


Jacobi does a lot of internal consistency checks and it prefers to crash rather than give you wrong results. If Jacobi crashes and you don't think it should have, then please e-mail me the problem you were trying to solve and approximately how long it took before the crash, so I can try to reproduce it.

One known way to crash Jacobi is with a ChecklessChess loop, like this one adapted from Popeye's BEISPIEL/exklohne.inp

auto Gerd Rinder
quel Seite 9, Die Schwalbe, X/1969
ford #1
bedi checkless
weis kd7 td8h8 la1h1
schw ke5 nc3f3

Offline use

Just bookmark the latest version page so you can get to it directly. This page contains an AppCache manifest which tells your browser to store every file needed by Jacobi on your computer/device so that the page still "loads" when offline in that particular browser. Some browsers even offer the option "Add to homescreen", which will turn Jacobi into a Web App that you can launch by clicking on an icon (as long as the browser remains installed and its application cache is not cleared).

Upcoming features

Here are the features I'm planning to add soon, so don't bother suggesting them! Jacobi will reach v1.0 when they are all implemented.


Jacobi is freeware, which means that you are free to use it and make a copy for personal use, but not to redistribute copies as I retain the Copyright on it.

The code for the interface is unobfuscated JavaScript, feel free to look at it and propose patches to me. On the other hand, the Chess engine is obfuscated JavaScript, having been compiled from C with Emscripten. I'm keeping the C source code private.


The problems that you enter are solved on your own computer using WebAssembly or JavaScript, and are not transmitted over the Internet.

Version history

Here I keep links to old versions. Useful to you if I break something with an update.

Fairy condition definitions

Please use these definition lists. None is truly complete, but combined they cover pretty much everything.

Page created: October 16, 2017
Page last updated: March 19, 2018

back to François Labelle's homepage