Girl Chess
Want to play it? Jump to Running the game locally: ten to fifteen minutes on a Mac, most of it downloads.
Instructions for how to run it are at the end of this page.
A personal AI chess tutor that runs locally on your machine. Play against mallow, human-feeling opponent at nine strengths, who's beatable due to warnings, progressive hints, and a plain-English debrief after every game. The repo ships 51 of my own finished games and 113 coach exchanges from them. The fastest way to assess a chess tutor is to read it coaching real mistakes.
I am a woman who learned chess 3 months ago in my 30s. Most chess apps felt cold and masculine, so I built the tutor I wanted: feminine-first and approachable, for an underserved slice of a massive market.
Gameplay: the opponent, the judge, and the coach
Three layers do the thinking. Stockfish does the chess math. Mallow is the human-feeling opponent ensconced in sugary marshmallow by the game's "Sugar Glitch" theming. Maia is an open source neural network from researchers at the University of Toronto, Cornell, and Microsoft Research that uses Lc0 (Leela Chess Zero) as its execution engine. While standard Lc0 plays to win at all costs using self-play calculation, Maia is trained on human games to predict human moves. It plugs directly into Lc0's framework but overrides its superhuman logic with human-like behavior. Claude Sonnet 5 writes the coach's chat answers and per-move notes, called through the Agent SDK, Anthropic's library for running Claude from code.
By default, selecting a move is not playing it. Click a piece, click a square, and the judge evaluates that move while your piece sits ghosted on the target. A second click or "play it" confirms; "take it back" retracts.
While a move is pending, the coach has two lines under the board. The hint ladder ("help?", then "more?") is written by code from the engine's search, so it can only say what the engine verified. The band beneath it is where the coach actually speaks: on a move the judge doesn't like, the second press opens it with "cookie is looking…" and Claude Sonnet 5 writes a deeper read of the position from those same engine facts, checked against them before it appears. The Coach Corner chat in the sidebar is held to the same rule. The post-game analysis uses no model at all. Every sentence in it is a hand-written template, chosen by rules from the game's turning points and filled in from a replay of the moves, which is why it can be checked line by line before a change ships.
Girl Chess is meant to be played on a computer, not on a phone or a small screen.
Move 2 of game 195. The knight is selected and sits ghosted on h3, not yet played. Before you confirm, the judge weighs the move and the hint tells you where to look; "more?" adds detail. "ask about this" opens the coach chat on that moment, so you can push back and get the reasoning, drawn from the same verified search as the hint.
Move 29 of another game, 21 points up: the judge nudges a winning move because a faster checkmate was there.
Players lose won games by failing to close them in the endgame (and middlegame conversion for that matter!). Can you spot the mate in 1 here?
The debrief
After the game the app builds a full debrief. Stockfish finds the turning points and the debrief writes them up in plain English, so you learn what decided the game without reading notation. Cards fall into three groups: done well, could be better, watch next time. Turning-point badges use seven fixed words (the slip, the crack, the punish). "ask about this" on a card opens the coach chat on that moment so the coach gives a stateful answer.
The debrief after beating mallow at 1600 (game 191 in the demo database).
"replay" puts the moment back on the board with arrows drawn. "try the line" drops you into play from the mistake so you can make the call again.
The move-4 turning point replayed: solid arrows for what happened, dashed for what didn't. Much clearer for beginners than algebraic chess notation!
Coach guardrails: hallucinations, voice drift, and overclaiming
The coach kept stating things about the board that weren't true, and the easy story was "try a bigger model" or "shrink the system prompt." I measured the baseline first. The cause was a fact gap: the coach reasoned from facts it never had. Feeding it the facts and holding it to them fixed it, not a bigger model. Those facts now come from the hint ladder's own verified search, for the position and any move you name but have not picked up (code improvements in September 2026). Placement errors went from 7.5% to 0 and explanation answers from 13 to 15 seconds to about 4. In the committed games, one first draft in nine still trips the placement check.
Two guardrails: every coach reply is checked before it reaches you, and the debrief code is checked before it ships. On questions about the board, a claim about a move, placement, defence or checkmate that the facts don't support gets one retry, then a written fallback answer. The check overcorrects: ten of the 113 committed chat replies ended in a fallback answer. That is the trade I chose, so nothing the checks can disprove reaches the player. The post-game analysis is written by code, not the model, from a replay of the game's own moves. Nineteen deterministic rules check it against that replay over every finished game in my history before any change can merge. That took the debrief's "you could have won faster" claims from 60% contradicted to about zero. docs/evaluation.md explains the checks, thinking budget iterations, and model comparisons; docs/technical-decisions.md has the fact-gap diagnosis.
Two limits:
- Missed checkmates are measured only on the flagged move, not the whole game, so a second one later in the game goes uncounted.
- My 1350 rating is a hard-coded placeholder anyone who downloads this inherits. A rating judged from how you actually play is on the roadmap.
How it's built
I designed and built this 0-to-1 as a product manager's first vibed project ever, via Claude Code: spec, plan, execute, adversarial review, gate. The spec came first: the PRD-lite names three hypotheses and the metric that would kill each one. A live playtest and evals drove each increment.
- Four text surfaces reach the player. Two are model-written, the coach chat and the per-move note; two are code, the hint ladder and the post-game analysis, templated from Stockfish facts.
npm run gate is the local merge check. It fails on any violation of the rules in src/review/debriefInvariants.ts. On a fresh clone with no personal database it runs those rules against the 51 committed games.- Skipping
setup.sh fails loudly: the server refuses to start and names the missing Elo bands. Deliberate. A missing Maia band used to silently swap in a strength-limited Stockfish, a far less human opponent.
data/girlchess-demo.db is committed on purpose: 51 games with full move lists, each coach reply's final draft with its validation result, my questions, and my thumbs. tools/make-demo-db.sh builds it from my live database through a read-only handle: finished games only, backend-error traces dropped. No names, addresses, emails or keys; I scanned it for them.
Docs and credits
The docs are published at tiffygk.github.io/girl-chess-demo, so none of them need a clone to read.
Built on Stockfish, Maia through lc0, and Claude Sonnet 5. The mistakes in the committed games are mine.
Running the game locally
You need a Mac (Apple silicon or Intel), Homebrew, and Node 22. Linux and Windows are not supported and not tested. If you are not sure what you have, run the first three commands below, then npm run doctor tells you what is missing.
Then open Terminal (press Command-Space, type Terminal, press Return) and paste these:
git clone https://github.com/tiffygk/girl-chess-demo.git
cd girl-chess-demo
npm ci # installs the project's packages, under a minute. lines about "vulnerabilities", "deprecated", or "funding" are npm noise, not a problem here.
./setup.sh # once: installs lc0 through Homebrew, the pinned Stockfish 19 into engines/ by checksum, and nine opponent files, 2 to 10 minutes. safe to run again.
npm run doctor # says what, if anything, is still missing and how to fix it
npm run dev # starts the game; the last line tells you the address to open
Open http://localhost:5173. You will see the board, a strength picker, and "start new game". Click a piece, then a square; the judge weighs the move while the piece sits ghosted, and "play it" confirms. Your games are saved to data/girlchess.db on your machine and never leave it. To browse the 51 games I played instead of starting empty, run npm run demo. The game runs only while that Terminal window is open; Ctrl+C or closing the window stops it. To play again later, open Terminal and run cd girl-chess-demo, then npm run dev.
The coach, cookie, needs you signed in to Claude on this Mac (the Claude Code app's sign-in; install it from https://claude.com/claude-code, run claude once in Terminal, and sign in). Without that, cookie says so in the chat panel, and everything else still works: the opponent, the judge's warnings and hints, and the full debrief after each game. If ANTHROPIC_API_KEY happens to be set in your shell, the coach ignores it and uses your Claude login only; nothing here bills a metered key. The API listens on 127.0.0.1 and refuses requests from other origins.
When something goes wrong, the message on screen says what to do. The ones you are most likely to meet:
| you see | do this |
|---|
port 3001 is already in use by another program | press Ctrl+C, then run PORT=3002 npm run dev (that moves both halves), or quit the other program |
Port 5173 is already in use | run VITE_PORT=5174 npm run dev and open the address it prints |
the game server is not running in the browser | look at Terminal: the server printed why; fix that, then click try again |
opponent files ... are missing or ... damaged | run ./setup.sh again; it fetches only what is missing or damaged |
Could not read package.json | you are not inside the folder: cd girl-chess-demo first |
Homebrew is not installed | https://brew.sh, then ./setup.sh again |
| cookie says she needs you signed in | the game works without her; to turn her on, install Claude Code, run claude once to sign in, restart with npm run dev |
npm run gate is the project's own check (tests, types, lint, and two rule-checkers over the 51 committed games), about three minutes. Its report is written for contributors; the last line is the verdict. Once you have finished five games of your own it checks those instead of the committed ones. It runs in GitHub Actions on every push, which is what the badge at the top reports.
