A universal chess analysis companion — multi-engine, book-aware, tablebase-backed, and undetectable by design.
BetterMint runs real chess engines next to any chess site and shows you what they think — ranked moves, arrows on the board, an evaluation bar, opening-book lines and endgame tablebase results. Eight engines are bundled and run inside your browser, so the basic setup needs no install, no server and no downloads.
If you want desktop-grade strength, the optional EngineWS companion runs native UCI engines (Stockfish, Lc0, Torch, anything UCI) on your machine and streams their analysis back.
Everything is optional, everything is configurable, and nothing is hardcoded.
- Eight built-in WebAssembly engines, no install required — Stockfish 18, Stockfish 18 NNUE, Torch 1, Torch 2, Stockfish 16 NNUE, Stockfish 16 (no SIMD), Stockfish Classic and an Explanation Engine.
- Run several at once. A priority order decides which engine supplies the #1, #2 and #3 move, so you can blend a tactical engine with a positional one.
- EngineWS companion for native desktop engines, with one-click downloads of the latest releases.
- Socket engines — Maia, Rodent personalities, Patricia, Fairy-Stockfish and every historical Stockfish version, over a raw-UCI WebSocket. No downloads.
- Per-engine UCI options are discovered automatically and exposed in the UI.
- Stage-aware knowledge. BetterMint knows whether you are in the opening, middlegame or endgame and asks the right source for each.
- Polyglot
.binbooks load directly in the browser and are binary-searched instantly. Assign each book to a stage. - Larger books from disk through EngineWS, plus Syzygy and Gaviota tablebases.
- Online 7-piece tablebase fallback that works with no setup at all, routed through the extension so the site never sees the request.
- Book moves render as dashed amber arrows with real win/draw/loss statistics.
- Humanizer — think time drawn from a bell curve, longer pauses at critical moments, faster play in time pressure, instant replies in known opening theory.
- A visible move distribution. Set the chance of the 2nd best, 3rd best and deeper moves, plus deliberate blunders with a cooldown, and see exactly what percentage the best move ends up with.
- Elo Match Skill scales strength, timing and mistake rate toward a target rating.
- Auto move, premoves and auto queue.
- Hand & Brain mode.
- Coach mode grades every move you play and explains why, using the familiar taxonomy — Brilliant, Great Find, Best, Excellent, Good, Book, Forced, Inaccuracy, Mistake, Missed Win, Blunder.
- Text-to-speech for moves and coaching, with an option to speak only mistakes.
- In-game HUD with an evaluation bar, ranked move list, depth readout and game-stage badge.
- Stream-proof window — a separate always-on-top window carrying the board, evaluation, engine lines and book lines, so nothing appears on the captured tab.
- Lua scripting with a documented API, worked examples and a built-in editor.
- Variants and Chess960 support.
- Automatic board detection — it finds the board on chess sites it has never seen before.
- Download or clone this repository.
- Open
chrome://extensionsand turn on Developer mode (top right). - Click Load unpacked and select the
BetterMintfolder. - Open any chess site. The HUD appears on its own.
That is the whole setup. The eight built-in engines work immediately.
Only needed for native desktop engines, disk-based books and local tablebases.
Requirements: Python 3.10 or newer.
cd EngineWS
pip install -r requirements.txt
python main.pyWindows users can just double-click run.bat.
On first run EngineWS creates its own config.json and prints something like:
==============================================================
BetterMint EngineWS v2.0
Dashboard: http://127.0.0.1:8000
Paste this into the extension's EngineWS address setting:
ws://127.0.0.1:8000/ws?token=XXXXXXXXXXXXXXXXXXXXXXXX
==============================================================
Copy that whole ws:// line into Settings → Engine → EngineWS URL in the extension.
Why a token? WebSockets are not covered by the browser's same-origin policy, so without one any page you happened to be visiting could connect to your local server and list your engines. The token closes that. Set
"require_token": falseinconfig.jsonif you would rather turn it off.
Open http://127.0.0.1:8000 for the dashboard: engine status, priority order, one-click engine downloads and book management.
| What you want | Where to go |
|---|---|
| Turn features on and off quickly | Dashboard → Quick Toggles |
| Depth, MultiPV, threads, which engines run | Settings → Engine |
| Think time, blunder rate, move distribution | Settings → Humanization |
| Auto move, premoves, which rank gets played | Settings → Auto Move |
| Move grading and spoken feedback | Settings → Coach Mode |
| Upload books, assign game stages | Books & TB |
| Maia and other hosted engines | Sockets |
| Custom scripts | Lua Scripting |
| Full explanation of every feature | Docs |
A tip worth knowing: MultiPV controls how many distinct lines the engines report, and that is what feeds the arrows, the ranked list and the humanizer's choice of move. If MultiPV is 1 there is only ever one move to choose from, so the humanizer cannot vary anything.
A smoke test ships with the server. Start EngineWS, then:
cd EngineWS
python smoke_test.pyIt reports every enabled engine's best move, every book that answered, and any tablebase hit — so you can tell at a glance whether a book is actually loading or an engine is silently failing.
- Book files must be polyglot
.bin. ChessBase CTG cannot be read; convert it first. - Simulated mouse input is off by default and should stay off. Synthetic events carry
isTrusted=falseand can be detected. The site-API path is the safe one. - Engines run in isolated workers in an extension-origin frame, so a site's Content-Security-Policy cannot block them and the page cannot see them.
This project is a collaborative effort made possible by:
- thedemons — Original creator
- ProtonDev — API docs & public API host
- BetterMint — Development and maintenance
See LICENSE.
v3.0.0 · undetectable by design