wtf is branch-predictor-simulator?

This is a small educational tool the author built to understand how CPUs guess the outcome of branching instructions before they actually run, a technique real processors use to keep their pipelines full and run faster. The simulator implements five different prediction strategies: always predicting taken, always predicting not taken, a simple one bit predictor, a more forgiving two bit predictor, and a more advanced GShare predictor that factors in recent branch history. To build it you need a C++17 compiler and the Make build tool, and building is a single command. You run the resulting program against a trace file, which is a plain text list of program counter addresses paired with whether that branch was actually taken or not. By default it uses the two bit predictor, but you can pick any of the five by name, tune GShare's internal table and history sizes, compare all five predictors against each other on the same trace at once, or turn on verbose mode to see every individual prediction and state change as it happens. The project includes its own test suite you can run with a single command. In the README, the author explains in plain terms what they learned: a one bit predictor flips its guess the moment it sees one different result, while a two bit predictor needs to be wrong more than once in a row before it changes its mind, and GShare improves on both by mixing the branch's address with a short history of recent branch outcomes to pick which prediction table entry to use. The author is upfront about its limits. It only models the direction of a branch, not real CPU timing or pipeline behavior, so it does not aim to be cycle accurate. It loads an entire trace into memory before running, so it is meant for small traces used for learning rather than large real world workloads, and its indexing into the prediction table uses the raw address bits without first removing the bits that come from instruction alignment.