> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Chess Lens

> Real-time chess coaching from a clearly visible board, with instant engine tips and AI explanations in a floating desktop overlay

<Card title="Chess Lens on GitHub" icon="github" href="https://github.com/video-db/chess-lens">
  Complete source code, installers, and troubleshooting
</Card>

## 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.

<Tip>
  **The Experience**: Keep playing in your preferred chess app while a draggable, always-on-top coach updates as the board position changes.
</Tip>

## What You Get

<Tabs>
  <Tab title="Instant Tips" icon="zap">
    ### 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.
  </Tab>

  <Tab title="AI Coaching" icon="brain">
    ### Understand the Position

    A plain-language explanation and drill question arrive in the background and update the overlay when ready.
  </Tab>

  <Tab title="Game History" icon="history">
    ### Revisit Past Sessions

    Chess Lens keeps a local history of sessions. When analysis is available, you can review the recording from VideoDB, coaching tips, key moments, win probability, and the post-game summary.
  </Tab>
</Tabs>

## How It Works

<Steps>
  <Step title="Capture the Board">
    Chess Lens starts a VideoDB capture session and watches the chess board shown on your screen.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Calculate the Best Move">
    The chess engine evaluates the position and returns a best move and score for the overlay.
  </Step>

  <Step title="Add Coaching Context">
    An AI-generated explanation and drill question are prepared in the background, then added to the existing engine tip.
  </Step>
</Steps>

<Info>
  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.
</Info>

## Key Features

<AccordionGroup>
  <Accordion title="Works Across Chess Apps" icon="app-window">
    Chess Lens reads the board from the screen instead of depending on a specific chess website or client integration.
  </Accordion>

  <Accordion title="Automatic Board Detection" icon="eye">
    Detects a clearly visible board from either the white or black perspective and updates when the position changes.
  </Accordion>

  <Accordion title="Floating Coaching Overlay" icon="message-square">
    A transparent, draggable, always-on-top window shows the board, current tip, coaching explanation, drill question, chat, and no-board state.
  </Accordion>

  <Accordion title="Session Review" icon="history">
    Browse past games and review available recordings, move history, win probability, key moments, coaching tips, and AI-generated post-session recaps.
  </Accordion>

  <Accordion title="Local-First History" icon="hard-drive">
    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.
  </Accordion>
</AccordionGroup>

## Getting Started

<Info>
  **Prerequisites**

  * macOS 12+ or 64-bit Windows 10+
  * A [VideoDB API key](https://console.videodb.io/auth?utm_source=docs_videodb_io\&utm_medium=docs_link\&utm_campaign=console_auth\&utm_content=docs_link\&id=docs)
  * Screen Recording permission on macOS
  * Microphone permission only if you enable audio recording or transcription
</Info>

<Tabs>
  <Tab title="macOS" icon="laptop">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/video-db/chess-lens/main/scripts/install.sh | bash
    ```

    Start Chess Lens from Applications or Spotlight after installation.
  </Tab>

  <Tab title="Windows" icon="monitor">
    Run in PowerShell:

    ```powershell theme={null}
    irm https://raw.githubusercontent.com/video-db/chess-lens/main/scripts/install.ps1 | iex
    ```

    Start Chess Lens from the Start Menu after installation.
  </Tab>

  <Tab title="From Source" icon="code">
    Requires Node.js 18+:

    ```bash theme={null}
    git clone https://github.com/video-db/chess-lens.git
    cd chess-lens
    npm install
    npm run dev
    ```
  </Tab>
</Tabs>

<Steps>
  <Step title="Add Your Details">
    On first launch, enter your name and VideoDB API key. You can get a key from [console.videodb.io](https://console.videodb.io/auth?utm_source=docs_videodb_io\&utm_medium=docs_link\&utm_campaign=console_auth\&utm_content=docs_link\&id=docs).
  </Step>

  <Step title="Grant Screen Access">
    On macOS, allow Screen Recording in **System Settings > Privacy & Security** so Chess Lens can see the board.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Follow the Overlay">
    Chess Lens detects position changes and updates the floating coach with the latest engine tip and explanation.
  </Step>
</Steps>

## 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.

***

<Card title="Complete Setup Guide on GitHub" icon="github" href="https://github.com/video-db/chess-lens">
  Installation, development commands, and detailed troubleshooting
</Card>

## Related Tutorials

<CardGroup cols={2}>
  <Card title="Focusd" icon="target" href="/examples-and-tutorials/ai-copilots/focusd">
    Turn desktop activity into useful summaries and work insights
  </Card>

  <Card title="Pair Programmer" icon="code" href="/examples-and-tutorials/ai-copilots/pair-programmer">
    Give coding agents real-time screen and audio context
  </Card>

  <Card title="Capture SDK Overview" icon="camera" href="/pages/ingest/capture-sdks/overview">
    Learn how to build screen-aware desktop applications
  </Card>
</CardGroup>