BetterChess

BetterChess

A chess coach that watches your live game and answers from your terminal.

Stats for Nerds:

• Team Size: 1
• Timeline: Ongoing
• Language: Python
• Framework(s):
  • berserk (Lichess API client)
  • python-chess
  • Stockfish / chess-api.com (evaluation)
  • google-genai (Gemini)
• Tools:
  • Lichess
  • Stockfish
  • Gemini (default gemini-3-flash-preview)
  • colorama
• Deployment: Runs locally — python main.py in your terminal
• Repository: https://github.com/Serrowxd/BetterChess

The Concept

What inspired you?

I wanted a coach sitting next to me while I play — not a post-game review that tells me what I should have done an hour later. BetterChess is a terminal chess coach: it watches your live Lichess game, keeps a synced model of the board, evaluates every position with an engine, and lets you ask an LLM coach questions in plain language as the game unfolds. “What’s the threat here?” “What’s my plan?” — answered against the real position, in real time.

It’s deliberately small. One python main.py, a Lichess token, and a Gemini key, and you’re playing with a coach over your shoulder.

How It Works

The pipeline

Three moving parts:

The watcher streams your game from Lichess on a background thread, rebuilds the board from the move list, and stays in sync as you and your opponent move.

The evaluator scores each new position — either a local Stockfish engine over UCI, or the hosted chess-api.com — and turns it into a human-readable evaluation string. This is what keeps the coach honest: the LLM isn’t guessing at the position, it’s grounded in an engine’s read of it.

The coach is a Gemini model with conversation history. Every position update is injected as hidden context — a tagged board-update message the model sees but is told never to repeat back. You talk to it through a terminal REPL; it answers concisely with practical advice, and any chess moves in its reply get highlighted in green.

The Design Choices

The decisions that make it feel right

Hidden board updates. The FEN and evaluation go in as silent context with a “do not repeat to the user” instruction, so the coach talks like a coach instead of narrating the board back at you.

Engine-grounded, not vibes. The LLM always answers against a real Stockfish/Chess-API evaluation of the live position — the language model explains and advises; the engine supplies the truth.

Bounded memory. The history gets trimmed down to the system prompt, the most recent board updates, and the last few conversation turns — so a long game doesn’t pile up and bury the coach in stale positions.

Concise and practical. It’s set up to give short, useful answers during a live game, not essays. Moves get colored green so advice is easy to scan with the clock running.

Status

Working and in use. It runs entirely locally — your Lichess token, your engine, your Gemini key — and pairs naturally with the rest of how I study the game: live coaching here, pattern tracking and game reviews in my notes afterward.