GitHub - tmythicator/lichess.el: A minimal Emacs client for the Lichess API

A minimal Emacs client for the Lichess API.

Showcase

Playing against AI

Challenge Stockfish and play directly from Emacs:

Playing against Friends & Strangers

You can also seek games against real humans in matchmaking (via M-x lichess-seek-game) or challenge your friends/specific players directly (via M-x lichess-challenge-user).

Lichess TV

Here is a quick demonstration of browsing Lichess TV and watching a live game:

Tournament Broadcasts

Follow live tournaments with a multi-board grid view:

Display Support Lichess.el is designed to work seamlessly in both GUI and terminal (emacs -nw) versions of Emacs. Rendering uses a simple text-based board for the best compatibility.

Features

• TV
  • [X] Live Lichess TV channels list (M-x lichess-tv)
  • [X] Select a game with RET to watch it live inside Emacs.
  • [X] Inspect any TV channel (M-x lichess-tv-debug)
• Tournament Broadcasts
  • [X] Browse live broadcasts (M-x lichess-broadcast-list)
  • [X] Watch round with auto-updates in grid view.
• Live Game Watcher
  • [X] Stream any Lichess game by its ID (M-x lichess-game-watch).
  • [X] Real-time board updates via the NDJSON stream.
  • [X] Full game history navigation with p (previous) and n (next).
  • [X] Switch board perspective with v (auto, white, black).
• Playing
  • [X] Challenge Lichess AI (M-x lichess-ai-challenge)
  • [X] Challenge Friends (M-x lichess-challenge-user)
  • [X] Seek / Matchmake against real opponents (M-x lichess-seek-game) (v1.0)
  • [X] Manage Challenges (M-x lichess-challenge-list) - List, Cancel, Accept.
  • [X] Make moves with m (UCI format)
  • [X] Resign with R
  • [X] Propose/Accept draw with D
  • [X] Mouse Support (v0.3): Click square to select/move pieces (GUI only).
• Core
  • [X] Interactive umbrella dispatcher (M-x lichess)
  • [X] Diagnostics: token + active games (M-x lichess-diagnose)
• FEN / Board
  • [X] Parse FEN -> internal position struct
  • [X] Render board (ASCII, Unicode, or SVG)
  • [X] Multiple board themes (Brown, Blue, Green)
  • [X] Header displays side-to-move, castling rights, en passant target, and perspective.
• Roadmap
  • [X] Watch a single game (lichess-game.el)
  • [X] Live board stream (NDJSON)
  • [X] Submit moves and play
  • [X] Challenge API (against AI)
  • [X] MELPA packaging
  • [X] GUI Rendering (SVG) (v0.2)
  • [X] Material Diff (v0.6)
  • [X] Tournament Broadcasts (v0.7)
  • [X] Matchmaking / Seek Game (v1.0)
  • [ ] Puzzles & tactics

Installation

Clone and add to your load path:

(add-to-list 'load-path "~/path/to/your/lichess")
(require 'lichess)

Configuration

Authentication

Some commands require a personal API token (e.g., playing games, viewing protected user data).

1. Go to https://lichess.org/account/oauth/token
2. Create a token with appropriate scopes.
3. Configure it in Emacs using either of the following methods:

Method A: Standard auth-source (Recommended)

Store your token securely using Emacs’s built-in auth-source library (available out-of-the-box). Add the following line to your ~/.authinfo or ~/.authinfo.gpg:

machine lichess.org password YOUR_TOKEN_HERE

No additional configuration is required in Emacs; the package will automatically resolve the token.

Method B: Variable Configuration

Alternatively, set the variable directly in your configuration file:

(setq lichess-token "YOUR_TOKEN_HERE")

Customization

You can configure Lichess.el using M-x customize-group RET lichess RET or by setting variables directly in your config.

Authentication

• lichess-token: Your personal API token. Required for playing games and viewing protected data.

Board Appearance

• lichess-board-gui-preferred-style: Style for GUI frames (“svg”, “unicode”, “ascii”). Default: “svg”.
• lichess-board-tui-preferred-style: Style for Terminal frames (“unicode”, “ascii”). Default: “unicode”.
• lichess-board-gui-light-square-color: Color for light squares. Default: “#f0d9b5”.
• lichess-board-gui-dark-square-color: Color for dark squares. Default: “#b58863”.
• lichess-core-chess-font: Font family for Unicode chess pieces. Key for alignment in non-graphical modes or fallback.
• lichess-board-gui-asset-path: Directory containing SVG piece assets.
• M-x lichess-board-gui-toggle-theme: Switch board color theme (Brown, Blue, Green)

Game Settings

• lichess-ai-default-level: Default Stockfish difficulty level (1-8). Default: 1.
• lichess-ai-default-clock-limit: Initial clock limit in minutes for AI games. Default: 5.
• lichess-ai-default-clock-increment: Clock increment in seconds for AI games. Default: 10.
• lichess-challenge-default-clock-limit: Initial clock limit in minutes for challenges against friends. Default: 5.
• lichess-challenge-default-clock-increment: Clock increment in seconds for challenges against friends. Default: 10.
• lichess-seek-default-time: Initial clock time in minutes for seeking games. Default: 5.
• lichess-seek-default-increment: Clock increment in seconds for seeking games. Default: 10.

Network & Performance

• lichess-tv-fetch-delay: Delay (seconds) between TV game fetches to prevent rate-limiting. Default: 0.12.
• lichess-util-eval-delay: Minimum delay (seconds) between cloud evaluation requests. Default: 1.0.
• lichess-board-gui-evaluation-gauge-width: Width of the evaluation gauge in pixels. Default: 12.

Accessibility

• lichess-announce-events: When non-nil, announce game events (moves, resignation, results) in the echo area for screen readers. Default: nil.
• lichess-announce-use-buffer: When non-nil, log all announcements to a persistent *Lichess Announcer* buffer. Default: nil.

use-package Example

Here is a complete configuration using use-package:

(use-package lichess
  :commands (lichess lichess-tv lichess-game-watch)
  :custom
  ;; Optional: set token directly (or use ~/.authinfo)
  ;; (lichess-token "YOUR_TOKEN")
  (lichess-core-chess-font "DejaVu Sans Mono")
  (lichess-board-gui-light-square-color "#f0d9b5")
  (lichess-board-gui-dark-square-color "#b58863")
  (lichess-ai-default-level 3))

Usage

• M-x lichess -> main entrypoint, shows dispatcher to all subcommands

Watching & Browsing

• M-x lichess-tv -> show Lichess TV channels list
  • g refreshes list
  • RET opens game on the current line
• M-x lichess-broadcast-list -> browse live tournament broadcasts
• M-x lichess-game-watch -> watch a specific game ID in real-time

Playing Games

• M-x lichess-ai-challenge -> play a game against Stockfish (AI)
• M-x lichess-challenge-user -> challenge a friend/specific user to a game
• M-x lichess-challenge-list -> list, accept, or cancel incoming/outgoing challenges
• M-x lichess-seek-game -> seek/matchmake game with a real opponent (stranger)
• M-x lichess-seek-cancel -> cancel the active real-time seek

How to Play

When in a game buffer (started via M-x lichess-ai-challenge):

• m -> Prompt for a move (UCI format, e.g., e2e4)
• R -> Resign the game (requires confirmation)
• D -> Propose or accept a draw (requires confirmation)
• K / Q -> Castle Kingside / Queenside (O-O / O-O-O)
• p / n -> Navigate move history
• v -> Cycle board perspective
• q -> Quit stream and close game

Development

See CONTRIBUTING.md for instructions on setting up the environment, running tests, and submitting pull requests.

Credits

Chess pieces by Colin M.L. Burnett, licensed under CC BY-SA 3.0.

License

GPL-3.0-or-later See LICENSE for details.