Chess with Me

Inspiration

Chess engines are extraordinarily strong. Strength is not the same thing as teaching.

When I review a game, Stockfish can tell me that a move is −2.3, show a better move, and dump a principal variation. That still leaves the questions I actually care about:

Why was my move a problem? What changed on the board? What should I have noticed? What is the idea behind the better move? Can you show me instead of giving me another wall of engine lines?

I wanted something closer to sitting beside a chess coach: play, ask in ordinary language, see the idea on the board, and trust that the sentence matches verified chess facts.

That became Chess with Me. The public coach is Mira.

This is a Collaborative Partner agent, not a chatbot wrapped around an engine. Mira classifies what I am asking, pulls only the chess data she is allowed to see, speaks, and can act on the board. She is forbidden from inventing chess truth.

Chess with Me is Open Alpha at https://chess-with-me.com/.

Disclosure. The playable product, Stockfish integration, teaching pipeline, and GCE VM predate 3 August 2026. This submission is the coaching-agent layer built in the contest window: Gemini 3.5 as the conversational partner, the API-feed-to-LLM briefing path, Google Gen AI SDK transport, and the admission / selection / publication discipline that stops one chess system from silently stealing another’s answer.

What it does

A user can play, review, ask for a hint, ask why a move was good or bad, and inspect a supported continuation on the board.

Two speakers, one chess authority:

Surface	Who speaks	Who owns chess truth
Hint / Explain / Compare	composed teaching publication	Stockfish + deterministic families + a closed public-answer boundary
Play chat (free text)	Gemini 3.5 narration of a speakable briefing	the same APIs; speakable fields only; not an internal JSON dump

The chat path is the agent loop that is live today:

player utterance
    → Gemini 3.5 classifies the need (not a multiple-choice form)
    → server builds a speakable briefing from chess APIs
    → Gemini 3.5 narrates only those facts
    → board actions (Demonstrate, Visual Aids) when evidence exists
    → POST /feedback → human teaching gate

If Gemini is down, chess still works. Chat becomes the generic Chat is unavailable right now. There is no mock success.

A detected fact is not automatically the lesson. Several true statements can exist at once — develop a piece, attack something, take the centre, remove a defender. Mira still has to decide what matters now.

How we built it

I built Chess with Me as a solo developer. I make the product decisions, define what the system is allowed to claim, design the contracts, and review whether a capability is ready to ship. AI coding tools (Codex, ChatGPT, Claude, Grok) do a lot of the implementation. My role is closer to a technical product owner than to a programmer typing every line.

The production system separates chess reasoning from conversation.

Search. Stockfish supplies legal search branches.
Deterministic analysis. Application code replays positions and verifies board facts: attacks, captures, defenders, checks, legal moves, supported tactics.
Candidates. Teaching families propose evidence-backed material. They do not own the final reply.
Admission / selection / publication. A fact must be allowed in, chosen as worth teaching, and pushed through one public-answer boundary (cwm.public_answer_content.v1) before the player sees it.
Narration. Gemini 3.5 Flash Lite, through the Google Gen AI SDK (@google/genai), classifies needs and speaks authorized facts. Local schema validators remain the final gate.

The public backend runs on Google Cloud Compute Engine (chess-with-me-prod, us-central1-a) behind Caddy at chess-with-me.com.

This split is also a cost decision. If deterministic chess code can answer a question, there is no reason to spend an LLM call rediscovering the same fact.

Challenges we ran into

The hardest problem was not generating more chess explanations.

It was deciding which explanation should reach the player when several systems all have something valid to say.

Earlier versions grew capabilities independently: static board analysis, Played-vs-Best, opening knowledge, hints, tactical detectors, fallback paragraphs. Individually, many of them worked. Together they failed. An early return in one path silently hid useful evidence from another. Played-vs-Best became a tactical black box. Adding another detector increased coupling instead of teaching coverage.

The question stopped being “how do I teach one more chess idea?” and became:

How can independent chess capabilities coexist without stealing, contradicting, or bypassing one another?

So I rebuilt around a shared pipeline:

candidate generation
       ↓
evidence
       ↓
admission
       ↓
priority / selection
       ↓
publication

That migration was painful because it touched code that already appeared to work. Fixing one layer exposed assumptions in another: activation, selection, composition, the public-answer API boundary, UI delivery, deployment, regression. That publication gate has already blown up live Explain more than once — a family serving an answer on one path and silently failing on another; a prefix / produce-gate mismatch returning HTTP 503; chat leaking into mechanical lessons. Repairing it is part of teaching quality, not a DTO chore.

A correct internal fact is not a public answer. Gemini may narrate only after publication (buttons) or after a speakable briefing (chat). It is not a second publisher.

Accomplishments that we're proud of

A first version of API-feed-to-LLM that is live on the public site: Gemini classifies a free-text need, the server builds a speakable briefing, Gemini narrates only those facts.

The two-speaker split actually shipped. Hint / Explain / Compare are composed lessons. Chat is a different speaker. Mixing them froze the wrong boundary, so keeping them apart is the accomplishment.

The public-answer gate is not a slide. It has already 503’d live Explain. Fixing that is teaching quality.

The product is Open Alpha at chess-with-me.com on GCE, built by one person. If Gemini is down, chess still works. There is no mock success.

What we learned

A correct answer is not automatically a useful answer.

A system can be technically perfect and still be a bad coach if it rarely says anything useful. A fluent unsupported explanation is worse than silence, because it damages trust.

I treat product quality as correctness and teaching utility. Unanswered positions stay in the denominator. Missing answers are not hidden to make coverage look better.

I also learned that implemented is not activated. A teaching family can exist in code and stay gated until evidence, wording, and regression are ready. Chat must not publish as a mechanical lesson.

Early users reminded me of the obvious: one tester first noticed that moving pieces was harder than it should have been. Another asked what made this different from existing chess AI, and only cared after I said the goal was a coach in human language, not another engine UI. Architecture means nothing if the user cannot feel the difference.

What's next for Chess with Me

Immediate work is broader, more useful coaching — not marketing.

Now. Public reports bind to the answer the server itself published. I still classify them by hand: valid teaching gap, skip, or (for chat) LLM-pipeline vs chess-principle. Valid gaps can take an AI-assisted chess-principle draft. Activation is still a human teaching gate.

Next, not in this demo. Use Gemini as a pre-processor on chess-with-me.com questions: summarise free-text question forms (not pick from a menu) and write those summaries back to the server. Count the forms. Widen, from that distribution, which engine-data slots the LLM is allowed to request. The chess pipeline should grow from observed questions, not from a larger prompt.

Longer term I want Mira to remember recurring mistakes and decision patterns instead of treating every game as an isolated session. Chess already has a measurement: rating.

The hypothesis is:

better explanations → better decisions → fewer repeated mistakes → stronger chess

The engine is already strong. The job is to make the chess understandable.