Skip to main content

Chess Lens on GitHub

Complete source code, installers, and troubleshooting

​
What Is It?

Chess Lens is a real-time chess coach that works directly from your screen. It watches a visible chess board, reconstructs the position in FEN notation, and shows the best move and evaluation in a floating overlay. A plain-language coaching explanation and drill question follow in the background, so you get a fast engine tip first and deeper guidance moments later. Because Chess Lens reads the board from screen capture, it can work with chess.com, lichess, ChessBase, or another chess client that displays a clear board.
The Experience: Keep playing in your preferred chess app while a draggable, always-on-top coach updates as the board position changes.

​
What You Get

​
See the Engine Move First

Chess Lens shows the best move and evaluation as soon as the chess engine responds, without waiting for the longer coaching explanation.

​
How It Works

1

Capture the Board

Chess Lens starts a VideoDB capture session and watches the chess board shown on your screen.
2

Recognize the Position

A vision model converts the visible board into FEN notation, a square-by-square representation used by chess software. Both white and black perspectives are supported.
3

Calculate the Best Move

The chess engine evaluates the position and returns a best move and score for the overlay.
4

Add Coaching Context

An AI-generated explanation and drill question are prepared in the background, then added to the existing engine tip.
Analysis refreshes when a new board position is confirmed. If the board is hidden or cannot be read for several frames, the overlay asks you to bring it back into view.

​
Key Features

Chess Lens reads the board from the screen instead of depending on a specific chess website or client integration.
Detects a clearly visible board from either the white or black perspective and updates when the position changes.
A transparent, draggable, always-on-top window shows the board, current tip, coaching explanation, drill question, chat, and no-board state.
Browse past games and review available recordings, move history, win probability, key moments, coaching tips, and AI-generated post-session recaps.
Session history and analysis metadata are stored in a local SQLite database. Screen recordings are captured through VideoDB, and model requests are processed outside the device.

​
Getting Started

Prerequisites
  • macOS 12+ or 64-bit Windows 10+
  • A VideoDB API key
  • Screen Recording permission on macOS
  • Microphone permission only if you enable audio recording or transcription
Start Chess Lens from Applications or Spotlight after installation.
1

Add Your Details

On first launch, enter your name and VideoDB API key. You can get a key from console.videodb.io.
2

Grant Screen Access

On macOS, allow Screen Recording in System Settings > Privacy & Security so Chess Lens can see the board.
3

Open a Chess Board

Start a game in your preferred chess website or desktop client. Keep the complete board visible and large enough to read.
4

Follow the Overlay

Chess Lens detects position changes and updates the floating coach with the latest engine tip and explanation.

​
If the Board Is Not Detected

  • Make sure the full board is visible and not covered by dialogs or other windows.
  • Bring the chess tab or app back into focus.
  • Increase the board size if the pieces and squares are difficult to read.
  • On macOS, confirm that Screen Recording permission is enabled.
  • Allow a few seconds for the first tip when a new position appears.

Complete Setup Guide on GitHub

Installation, development commands, and detailed troubleshooting

Focusd

Turn desktop activity into useful summaries and work insights

Pair Programmer

Give coding agents real-time screen and audio context

Capture SDK Overview

Learn how to build screen-aware desktop applications