A minimal Emacs client for the Lichess API.

Challenge Stockfish and play directly from Emacs:

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

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

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.

• 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

Clone and add to your load path:

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

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:

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.

Alternatively, set the variable directly in your configuration file:

(setq lichess-token "YOUR_TOKEN_HERE")

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

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

• 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)

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

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

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

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))

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

• 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

• 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

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

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

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

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