wordler is a C++ program to help you solve Wordle puzzles by suggesting which word to guess next.

The source code for wordler is available on GitHub.

How to Build

wordler.sln is the project file to build wordler using Microsoft Visual Studio on Windows.

I have not tried to build wordler on other systems, but I think it should work with a recent version of gcc or clang on Linux or MacOS.

The source code is in these files:

• main.cpp
• cmdline.h
• timer.h
• words-guess.h, words-target.h – word lists

The code uses some C++23 features.

How to Use

After entering a guess into Wordle, run wordler with your guesses and Wordle’s hints as arguments. It will compute a good word for your next guess.

For example, if your first guess is “learn” and Wordle displays this:

you would run wordler learn .g.y. Note that the hint is specified by using ‘g’ for a green letter, ‘y’ for a yellow letter, and ‘.’ for a grey letter.

Enter wordler’s guess into Wordle to get another hint. Then, run wordler again with both hints to get the next guess. For example:

And so on, until the game is over.

Other Options

wordler can be used in other ways. The --help option will display all of the command-line options. Here are the fun ones:

--play

Play a game!

--solve <word>

Solve for the given answer word

--all

Solve all possible answer words (this takes a long time!)

--stats <file>

Display stats from a results file that was produced by --all

How Good Is It?

wordler can always win Wordle – that is, it can solve any Wordle game in 6 guesses or less, and almost always in 3 or 4 guesses. This was tested against words-target.txt which, as far as I can tell, contains all possible answers. The file results.txt lists the number of guesses required to solve any answer.

On my old desktop PC, it can take up to 30 seconds for wordler to compute a guess given one hint. With more hints it is much faster.

How It Works

Word Lists

Wordle’s guesses and answers must be valid 5-letter English words. But the game actually has two different lists of valid words:

Answers are always ordinary words that most people know. These are listed in the file words-target.txt.

Guesses can be any 5-letter word, including many that you’ve never heard of. (“aahed“? ”cloot”?? “zymic”???) These are in words-guess.txt (to which the words in words-target.txt must be added).

Please note that the word lists used here come from an earlier version of Wordle for which these lists were available. Since then, Wordle has changed its word lists so the lists here are not completely accurate. I have been making corrections as I find errors, but it’s possible that you could run into a guess that isn’t accepted or an answer that cannot be found.

Heuristic

wordler’s job is to come up with a good next guess, based on the hints Wordle has given so far. So, what makes a “good guess”?

The heuristic used here is that a good guess is one that is likely to result in a good hint – that is, a hint that will cut down the set of possible answers as much as possible.

Since the correct answer word is unknown, wordler tests each guess word against all plausible answers and takes the average number of answers that would remain. Then it picks the guess with the lowest average.

Algorithm

Here is how wordler computes the next guess.

First, filter the list of all possible answers by matching them against the hints given on the command line. This results in a list of target words that match the given hints. The correct answer is in this list somewhere.

Then evaluate every possible guess word. Each guess must be tested against every target word.

• For each target word:
• Generate the hint that Wordle would give if this target word were the correct answer.
• Filter the target list by matching against this hint and count how many matching words remain.
• The total count over all target words is the score for this guess.

Select the guess word with the lowest score. This is the word that can be expected, on average, to result in a hint that cuts down the list of target words as much as possible.