A minimal Emacs client for the Lichess API.

Challenge Stockfish and play directly from Emacs:

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

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)
• 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] 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 or Unicode)
  • [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) vs TUI separation (lichess-board.el) (v0.2)
  • [ ] UI Improvements
    • [X] Opponent and user rendering (names, ratings)
    • [X] Show remaining time (clock)
    • [ ] On-screen keybindings info
    • [X] General status updates
  • [ ] 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:

(setq lichess-token "YOUR_TOKEN_HERE")

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

• lichess-core-chess-font: Font family for Unicode chess pieces (GUI only). If the board looks misaligned, try setting this to a monospaced font like “DejaVu Sans Mono”.
• 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-board-gui-preferred-style: Preferred style for GUI frames (“gui”, “unicode”, “ascii”).
• lichess-board-tui-preferred-style: Preferred style for Terminal frames (“unicode”, “ascii”).

  (setq lichess-core-chess-font "DejaVu Sans Mono")
  (setq lichess-board-gui-light-square-color "#e1e1e1")
  (setq lichess-board-gui-dark-square-color "#8b4513")
      

• lichess-ai-default-level: Default Stockfish level (1-8).
• lichess-ai-default-clock-limit: Clock limit in seconds.
• lichess-ai-default-clock-increment: Clock increment in seconds.

• lichess-tv-fetch-delay: Delay (seconds) between TV game fetches to avoid rate limits (default 0.12).
• lichess-util-eval-delay: Minimum delay (seconds) between cloud evaluation requests (default 1.0).

Here is a complete configuration using use-package:

(use-package lichess
  :commands (lichess lichess-tv lichess-game-watch)
  :custom
  (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 TV channels list
  • g refreshes list
  • RET opens game on the current line
• M-x lichess-ai-challenge -> start a new game against Stockfish
• M-x lichess-game-watch -> watch a specific game ID

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)
• p / n -> Navigate move history
• v -> Cycle board perspective
• q -> Quit stream and close game

This project uses a Makefile for common development tasks. If you use Nix, you can enter a reproducible environment with all dependencies pre-installed.

You can use direnv to automatically load the dependencies when you enter the directory:

direnv allow

Alternatively, enter the environment manually:

nix develop

• Format code: make format (uses elisp-autofmt)
• Run tests: make test
• Lint: make lint (uses package-lint)
• Byte-compile: make compile
• Clean: make clean (removes .elc files)

All pull requests are automatically checked for formatting, linting, and tests via GitHub Actions.

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

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