AI Brings Human Context to Chess Post-Mortems

Overview

A new open-source initiative is transforming how chess players analyze their games by merging engine precision with human cognitive context. The project, hosted under the repository brumar/chess-postmortem-skills, introduces a suite of skills for Claude Code that go beyond standard Stockfish evaluations. Instead of delivering cold numerical assessments, the tool provides plain-language explanations of mistakes, contextualized against the player’s own thoughts during the game.

This approach addresses a persistent gap in chess training: while engines can identify blunders with mathematical certainty, they often fail to explain why a specific thought process led to an error. By integrating audio recordings or written notes from the player, the system creates a post-mortem that refutes actual reasoning rather than hypothetical alternatives. The result is a narrated video and detailed analysis that bridges the divide between algorithmic perfection and human understanding.

How It Works

The core innovation lies in the synchronization of human thought with engine verification. During a game, particularly in slower time controls like rapid or correspondence chess, players are encouraged to record themselves thinking aloud. This can be done using a simple voice recorder or by taking written notes per move. After the game, the user provides the Lichess link and the audio file to Claude Code.

The system first transcribes the audio locally using whisper.cpp. It then aligns each sentence with the specific move being considered by cross-referencing the timestamps in the Portable Game Notation (PGN) with the game clock. This alignment ensures that when the analysis discusses a decision, such as whether a bishop belongs on c4 or e2, it is referencing the player’s genuine internal dialogue at that exact moment.

Once the transcript is aligned, the AI drives Stockfish to investigate the position. Rather than simply outputting the best move, the system poses naive questions a human might ask, such as "what if Black simply takes?" or "why not the move I played?" It iteratively queries the engine until the explanation is coherent and accessible. Every claim is verified against the engine, and a final verifier pass re-reads the results to minimize hallucinations.

The Skills Ecosystem

The repository provides three distinct skills designed to handle different aspects of chess analysis and play:

• chess-analysis: This is the primary tool for post-mortems. It performs a Stockfish sweep of every move and deploys parallel "investigator" subagents to interrogate the engine. These subagents focus on explaining mistakes through naive questioning. The output includes a layered annotated PGN, a standalone HTML analysis board, and a "plan pause" where both sides' strategic intentions are derived from the engine. It also handles the transcription and alignment of think-aloud recordings.
• chess-video: This skill generates a narrated video of the entire game. It creates a storyboard from the analysis and produces a video file featuring the board, tactical arrows, an evaluation gauge, and subtitles. The narration is generated using piper TTS, resulting in a polished, watchable summary of the game’s key moments.
• chess-play: Designed for interactive practice, this skill allows users to play games against Claude Code over PGN files. The board is rendered to PNG images for visual processing, and adversarial blunder-check subagents operate in the background. Notably, this skill does not use an engine, focusing instead on vision-based interaction.

Practical Considerations and Workflow

The tool is not intended for quick blitz analysis. A full run, including the engine sweep, investigation, annotations, and video generation, can take approximately one hour of processing time. Therefore, it is best suited for games where the player invested significant thought, such as 15+10 rapid games or correspondence matches. For faster games, traditional analysis tools on platforms like Lichess or Chess.com remain more efficient.

The workflow begins with playing a game while recording thoughts aloud. After the match, the user opens Claude Code and inputs the game link along with the audio file. Following the analysis phase, the user can request the video generation and then engage in a dialogue with the AI, asking questions about positions they still find unclear. The AI checks these queries against the engine before responding, ensuring factual accuracy.

Installation requires copying the skill folders into the ~/.claude/skills/ directory. While the setup involves dependencies such as python-chess, cairosvg, pillow, and ffmpeg, Claude Code is designed to install these automatically upon request. The documentation is integrated directly into the SKILL.md files, allowing users to learn the capabilities by reading the source code itself.

Impact on Chess Learning

This development marks a shift from passive consumption of engine lines to active engagement with one’s own cognitive biases. Traditional analysis often leaves players confused about why a particular move was bad if it felt intuitive at the time. By contrasting the engine’s findings with the player’s recorded thoughts, the tool highlights specific misconceptions, such as justified fears or flawed plans.

The ability to ask follow-up questions about any position further enhances the learning experience. Players can explore alternative variations and receive answers vetted by Stockfish, fostering a deeper understanding of strategic concepts. As AI tools become more capable of driving complex workflows, applications like this demonstrate how technology can respect and incorporate human context, making high-level analysis accessible and personally relevant.