♛♔ Play chess against UCI engines in your terminal.



♛♔ 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
  • Automatically save PGN in engine v. engine game.

    Automatically save PGN in engine v. engine game.

    Request uchess feature to permit automatic saving of PGN output in engine v. engine games, similar to that of cutechess-cli.

    For example: .\cutechess-cli -tournament gauntlet -concurrency 1 -pgnout lc0-stockfish-1.pgn -engine conf=lc0 -engine conf=stockfish -each proto=uci ponder tc=10+1 -openings file=openings-6ply-1000.pgn -repeat -recover -rounds 100 -games 2 | tee ./lc0-stockfish-1.txt

    During a engine v engine game, it is currently not possible to enter any commands into the interactive shell. Only pressing ENTER for the next move is permitted.

    opened by trumptonshire 3
  • Set Time Control when playing between two engines

    Set Time Control when playing between two engines

    Is it possible to add the functionality to set time control when two engines are playing each other, to moves are automatic, without having to press ENTER each time? For example, with cutechess-cli I use tc=10+1

    opened by trumptonshire 3
  • 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
A cli to play chess against an an UCI engine of your choice, written in go

chess-cli chess-cli is a cli for playing chess against an UCI compatible engine written in go Note: Chess pieces are in unicode, so the color may seem

Nemo 0 Dec 24, 2021
Blunder is an open-source UCI compatible chess engine.

A UCI compatible chess engine written in Golang

Christian Dean 187 Jun 13, 2022
Play chess in your terminal

Gambit Chess board in your terminal. Warning gambit does not have many features at the moment. I plan on adding a chess engine, mouse support, timers,

Maas Lalani 388 Jun 24, 2022
Chesscode - a way of encoding messages using a chess board and the starting set of chess pieces

chesscode Are you a spy that needs to leave an urgent top secret message for an

Logan Spears 57 May 12, 2022
Chesscode - Chesscode: a way of encoding messages using a chess board and the starting set of chess pieces

chesscode Are you a spy that needs to leave an urgent top secret message for an

Logan Spears 11 Jan 1, 2022
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 114 Jun 6, 2022
A terminal Snake game that supports multiple players to play together online.

GoSnake A Snake game that supports multiple players to play together online. The game is written in go language and does not use other third-party lib

StevE Zhang 2 Jun 25, 2022
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 16 Apr 18, 2022
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 16 Apr 18, 2022
chess package for go

chess Introduction chess is a set of go packages which provide common chess utilities such as move generation, turn management, checkmate detection, P

Logan Spears 367 Jun 23, 2022
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 28 Jun 16, 2022
A small go program that solves the Queen's Gambit chess puzzle.

Queen's Gambit Solver This program attempts to solve the Queen's Gambit each time it is run. The Queen's Gambit is a chess-based puzzle where eight qu

Edward Hahn 2 Dec 16, 2021
A simple chess engine for experiment, made in Golang

chess-engine A simple chess engine for experiment, made in Golang Build the engine Run the command make or make build Run the engine Run the command f

Samuel Custodio 1 Dec 26, 2021
chess.com api wrapper for go

Chessdotcom-go An unofficial, simple, lighweight API wrapper for chess.com written in go Usage go get -u "github.com/ATTron/chessdotcom-go" im

Anthony Templeton 0 Dec 31, 2021
A chess server built with Temporal.

chesstempo A chess server built with Temporal. Dependencies The activity worker runs Stockfish in the background. In Debian-based distros, you can ins

Jesús García Crespo 11 May 14, 2022
basicbots is a programming game where you program your robot to compete against other robot.

basicbots What is baiscbots? basicbots is a programming game where you program your robot to compete agaist other robots. What is the inspiration? My

Bill Jones 23 Jan 8, 2022
lets play a game

Flashbots is a research and development organization formed to mitigate the negative externalities and existential risks posed by miner-extractable value (MEV) to smart-contract blockchains.

@edgararout 59 Jul 9, 2021
Golang RISC-V emulator that can play DOOM

RISC-V Emulator A toy Golang RISC-V emulator that can play DOOM For now it uses smunaut bootloader and riscv_doom from the ICE40 project. But since th

Lucas Teske 38 May 23, 2022
Awesome 2D Maze-based games to play with kids in family and with friends on rich console UI. developed into Go.

gomazes Have fun time with kids and family and friends at playing awesome 2D maze-based games while feeling like a programmer on the computer console/

Jerome Amon 1 Dec 23, 2021