♛♔ Play chess against UCI engines in your terminal.

Related tags



♛♔ Play chess in your terminal.

GitHub issues GitHub forks GitHub license Go Report Card

uchess screenshot


uchess is an interactive terminal chess client designed to allow gameplay and move analysis in conjunction with UCI chess engines.

uchess is highly configurable, fully themeable, and capable of supporting a variety of play scenarios including human vs. human, human vs. cpu, and cpu vs. cpu.

Games may be initialized via FEN notation and exported to PGN notation for further analysis in third-party engines. Additionally, board snapshots may be saved to SVG image format for the purpose of sharing or archiving board state.

A hint engine is provided to assist players in discovering the best move in a given scenario and game state may be walked backward on an as-needed basis to facilitate game tree exploration.

Game moves are input as algebraic notation via an interactive command shell, and a variety of auxillary commands are supported.

An example of a board snapshot:

uchess board snapshot


The easiest way to get uchess is via an official release.

uchess can also be installed using "go get". A valid GOPATH is required to use the go get command. If $GOPATH is not specified, $HOME/go will be used by default.

$ go get github.com/tmountain/uchess/cmd/uchess


uchess includes a Makefile which will build a binary for your native architecture.

$ make build
$ cmd/uchess/uchess

You can also cross compile via make release_test.

$ make release_test
$ tree dist
├── uchess_darwin_amd64
│   └── uchess
├── uchess_linux_amd64
│   └── uchess
├── uchess_linux_arm_5
│   └── uchess
└── uchess_windows_amd64
    └── uchess.exe
go get -u github.com/tmountain/uchess/cmd/uchess


The easy way: zero configuration

With no arguments specified, uchess will attempt to locate stockfish in your path and run it with difficulty level 20.

If stockfish cannot be found, uchess provides for an automated installation on Linux and Windows. Automated install for Mac is a work in progress.

The manual way: generate a uchess config and edit it accordingly.

Mac and Linux

$ uchess -tmpl > uchess.json


# Avoid BOM in config file
> .\uchess.exe -tpl | set-content uchess.json -Encoding Ascii

Run uchess on the config.

Mac and Linux

$ uchess -cfg uchess.json


> .\uchess.exe -cfg uchess.json


uchess accepts commands via an interactive shell. The following commands are supported.

  back           Walk the game state back one turn.
  save           Save the PGN for the current game in the CWD.
  image          Save an SVG snapshot of the current game in the CWD.
  fen            Display the FEN string for the current game.
  reset          Reset the board to the default FEN.
  resign         The current player resigns.
  hint           Highlight the recommended move using the hint engine.
  quit           Shutdown uchess immediately without saving game state.

If none of the previous commands are recognized, the input is assumed to be a move specified in algebraic notation.

      e4         Pawn to e4.
      exd5       Pawn on the e-file captures the piece on d5.
      O-O        King castles on kingside.
      O-O-O      King castles on queenside.
      e8=Q       Pawn promotion to queen.

Config Example

  "uciWhite": "stockfish",
  "uciBlack": "stockfish",
  "uciHint": "stockfish",
  "uciEngines": [
      "name": "stockfish",
      "engine": "/usr/games/stockfish",
      "hash": 128,
      "ponder": false,
      "ownBook": false,
      "multiPV": 4,
      "depth": 0,
      "searchMoves": "",
      "moveTime": 3000,
      "options": [
          "name": "skill level",
          "value": "20"
  "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
  "activeTheme": "basic",
  "theme": [
      "name": "basic",
      "moveLabelBg": "#d0d0d0",
      "moveLabelFg": "#000000",
      "squareDark": "#d78700",
      "squareLight": "#ffaf5f",
      "squareHigh": "#5fffaf",
      "squareHint": "#af87ff",
      "squareCheck": "#ff87d7",
      "white": "#eeeeee",
      "black": "#080808",
      "msg": "#d70000",
      "rank": "#9e9e9e",
      "file": "#9e9e9e",
      "prompt": "#d70000",
      "meterBase": "#585858",
      "meterMid": "#0",
      "meterNeutral": "#00d7ff",
      "meterWin": "#87ffd7",
      "meterLose": "#d75f5f",
      "playerNames": "#0",
      "score": "#9e9e9e",
      "moveBox": "#0",
      "emoji": "#0",
      "input": "#0",
      "advantage": "#9e9e9e"
  "whitePiece": "human",
  "blackPiece": "cpu",
  "whiteName": "",
  "blackName": ""

Base Config Format

When invoked with the -tmpl argument, uchess will generate a config with a reasonable set of defaults. The config file is a JSON document with the following top-level keys.

  uciWhite       Name of the UCI engine controlling white pieces.
  uciBlack       Name of the UCI engine controlling black pieces.
  uciHint        Name of the UCI engine providing hints.
  uciEngines     A list of available UCI engines (see UCI CONFIG FORMAT).
  fen            FEN notation specifying starting positions.
  activeTheme    The currently selected theme (list available via -themes).
  theme          A list of available themes (see THEMES).
  whitePiece     Player controlling the white pieces (cpu or human).
  blackPiece     Player controlling the black pieces (cpu or human).
  whiteName      Player name for white pieces in UI.
  blackName      Player name for black pieces in UI.

UCI Config Format

The uchess config file may reference any number of UCI engines; however, each engine must by identified by a unique name parameter. The following keys are supported for UCI configuration.

  name           The unique UCI engine name.
  engine         The path to the UCI engine binary (OS dependent).
  hash           The value in MB for hash table memory.
  ponder         Allow or disallow the engine to ponder.
  ownBook        Specifies whether the engine has its own opening book.
  multiPV        The engine supports multi best line or k-best mode.
  depth          Search x plies only. A setting of 0 specifies unlimited plies.
  searchMoves    Restrict search to moves specified (i.e., "e2e4 d2d4").
  moveTime       Search exactly x mseconds.
  options        Key-value pairs for arbitrary engine commands.


uchess is fully themeable, and user specified themes may be added to the uchess config file. The theme keys are named in a manner which is intended to be self-explanatory, and colors are specified by their respective hex values. It is recommended to limit colors to the spectrum supported by your terminal. xterm-256 (8-bit color) is the official standard for builtin themes.

The builtin themes are packaged into the uchess binary using Golang's embed package. New themes should be added to the themes project directory.

Pull requests for new builtin themes are welcome; however, the specified colors must fall under the xterm-256 standard. A color chart is available here.

Builtin themes should be specified on a one theme per file basis, and all themes should be specified in JSON format and reside in the themes directory.

When a name collision occurs, themes specified in the config file will override builtin themes.

Lastly, a special hex code of #0 is used to specify the terminal default color. This code should be used for any UI elements that may collide with an underlying color scheme (i.e., avoiding white fonts on white backgrounds).

Game Outcomes

uchess can effectively identify a wide variety of game outcomes, and it should account for the following end-game scenarios:

    Resignation (manual)
    Threefold Repetition
    Fivefold Repetition
    Fifty Move Rule
    Seventy Five Move Rule
    Insufficient Material

CPU Matches

If the uchess config specifies both whitePiece and blackPiece as cpu, the specified UCI engines will play against each other. The game will cycle forward one move each time tne enter key is pressed.

Platform Support

uchess has been tested and confirmed to work on Linux, MacOS, and Windows (PowerShell) platforms. It should work with a wide variety of terminals.

Project Status

uchess is currently in unstable (alpha) status, and its internal APIs are subject to change. Efforts will be made to keep the config file and theme format stable going forward to the extent that it is practical to do so.


Some UCI chess engines currently fail due to a lack of proper initialization. This will be resolved in a future release. For the moment, stockfish is the only UCI engine that is officially supported.

Special Thanks

uchess depends on the notnil/chess, and freeve/uci, and gdamore/tcell modules. Many thanks to the maintainers.

Lastly, uchess is heavily inspired by nickzuber/chs.

  • Doesn't run on windows powershell

    Doesn't run on windows powershell

    On startup of the windows release binary, i get the following:

    > .\uchess_0.1.0_windows_x86_64.exe
    panic: theme: no theme found                                                                                                                                                                                                                    
    goroutine 1 [running]:
        /Users/traviswhitton/Projects/uchess/cmd/uchess/main.go:25 +0x753

    Trying to run via the source code on windows attempts to find stockfish at /usr/bin/stockfish, which is a linux path. Do i need to manually install stockfish and edit the path?

    Either way, i assume something went wrong with pkger during built of your windows release executable.

    opened by Bios-Marcel 9
  • Fixed misspelling of

    Fixed misspelling of "-tmpl" as "-tpl"

    The -tmpl flag was misspelled in the example.

    opened by servusDei2018 1
  • Is castling supported

    Is castling supported

    I've tried doing castling and it doesn't seem to work.

    I've tried the following:



    While the readme answers my question, it didn't work nonetheless and I don't understand why. There was nothing inbetween my king and I see no reason why it wouldn't ahve worked. Is it possible to print the actual reason for being unable to move?

    opened by Bios-Marcel 6
Travis Whitton
Travis Whitton
♛♔ Play chess against UCI engines in your terminal.

uchess ♛♔ Play chess in your terminal. Introduction uchess is an interactive terminal chess client designed to allow gameplay and move analysis in con

Travis Whitton 30 Jul 11, 2021
Currently in beta testing. A chess engine written in golang

Weasel Art graciously provided by Alex Table of Contents: About Installing and Compiling from Source Contributing License About Weasel is an 0x88 and

Weasel 14 Jun 25, 2021
A chess GUI build using the Fyne toolkit.

Chess The subject of my current live stream series. A simple chess UI built with Fyne. Thanks to: Chess Go library by Logan Spears github.com/notnil/c

Andy Williams 12 Jun 30, 2021
A chess engine written in golang

Weasel Art graciously provided by Alex Table of Contents: About Installing and Compiling from Source Contributing License About Weasel is an 0x88 and

WeaselChess Club 14 Jun 25, 2021
Play chess with Go, HTML5, WebSockets and random strangers!

ChessBuddy Play chess with Go, HTML5, WebSockets and random strangers! Demo: http://chess.tux21b.org:8000/ Hint: Open the page in two different tabs,

Christoph Hack 113 Nov 22, 2020
Web-based Cloud Gaming service for Retro Game

CloudRetro provides an open-source cloud gaming platform for retro games. It started as an experiment for testing cloud gaming performance with WebRTC and libretro, and now it aims to deliver the most modern and convenient gaming experience through the technology.

giongto35 1.5k Jul 23, 2021
A small fantasy game engine in WASM using GoLang

The GoLang Fantasy Engine (GoLF Engine) is a retro game engine. It draws inspiration from fantasy console projects like pico-8, tic-80, and pyxle. Like those projects it is designed to be a retro-feeling game creation/playing tool. Unlike those projects GoLF is more minimal in scope and only provides an API and a small set of tools to help you create your games. Tools like an image editor and code editor are not built in. Despite this minimalism creating games in GoLF is still easy and should still maintain the retro game feel.

Brandon Atkinson 75 Jun 7, 2021
🕹️ A basic gameboy emulator with terminal "Cloud Gaming" support

Gameboy.Live ??️ Gameboy.Live is a Gameboy emulator written in go for learning purposes. You can simply play Gameboy games on your desktop: Or, "Cloud

AaronLiu 4.2k Jul 26, 2021
Snake game made in Go! 🐍

Snake This is a Terminal based snake game made by tristangoossens. Please star this repository to help my first big project grow! Documentation can be

Tristan Goossens 294 Jul 18, 2021
Gopher2600 is an Atari 2600/VCS Emulator.

Gopher2600 Gopher2600 is an emulator for the Atari 2600 written in the Go language. The accuracy of the emulation is very high and the 6507, TIA and R

Stephen Illingworth 128 Jul 22, 2021
Terminal-based game engine for Go, built on top of Termbox

Termloop Termloop is a pure Go game engine for the terminal, built on top of the excellent Termbox. It provides a simple render loop for building game

Joel Auterson 1.2k Jul 18, 2021
SDL2 binding for Go

SDL2 binding for Go go-sdl2 is SDL2 wrapped for Go users. It enables interoperability between Go and the SDL2 library which is written in C. That mean

Ve & Co. 1.6k Jul 26, 2021
Open source of the build infrastructure used by Stadia Games & Entertainment

SG&E Monorepo This repository contains the open sourcing of the infrastructure developed by Stadia Games & Entertainment (SG&E) to run its operations.

Google 46 Jul 9, 2021
An open source re-implementation of Diablo 2

OpenDiablo2 Join us on Discord! Development Live stream Support us on Patreon We are also working on a toolset: https://github.com/OpenDiablo2/HellSpa

OpenDiablo2 9.6k Jul 26, 2021