Console Chess

TUI chess in Java — play against your choice of AI engines in your terminal.

Quick Start

./scripts/chess.sh play

This builds the JVM distribution if needed, then launches the game.

Install

Install the native binary via Homebrew:

brew tap d-led/homebrew-d-led
brew install console-chess

On Windows, install via Chocolatey:

choco install console-chess

See the package at Chocolatey.

Downloads

Pre-built native binaries from the latest main build:

Platform	Download
Linux x64	console-chess-linux
macOS arm64	console-chess-macos-arm64
Windows x64	console-chess-windows.exe

Unzip, make executable (chmod +x console-chess), then run ./console-chess.

Windows

On Windows, run the native binary from Windows Terminal (the Windows 11 default) or a VT-enabled console:

.\console-chess.exe

The binary bundles JLine's JNI terminal provider, so it needs no extra install. The board is drawn through the Unicode console API, so chess glyphs render regardless of the console code page — no chcp change required. If you run it in a legacy conhost window and the pieces show as garbage, switch the console font to a Unicode one (e.g. Cascadia Mono) or use Windows Terminal.

Controls

Key	Action
Arrows / hjkl	Move cursor
Enter / Space	Select piece, confirm move
q	Quit

Version

console-chess --version   # or -V

The version is resolved at build time in priority order: an explicit -Pversion=x.y.z (the release workflow passes the tag), then the vX.Y.Z git tag on the current commit, then 0.0.0-SNAPSHOT.

Engines

Four engines behind a common ChessEngine interface. Select with -e:

./scripts/chess.sh play       # default: noise, medium
console-chess -e noise -d easy        # ELO ~750
console-chess -e noise -d hard        # ELO ~1250
console-chess -e adam                 # ELO ~1600, minimax + piece-square tables
console-chess -e greedy               # ELO ~500, captures everything
console-chess -e stockfish -d easy    # Stockfish capped at ELO 1350
console-chess -e stockfish -d hard    # Stockfish capped at ELO 2800
console-chess -e noise -d medium -s 42  # reproducible with seed

The stockfish engine runs the Stockfish chess engine as a subprocess over the UCI protocol. brew install console-chess and choco install console-chess install Stockfish automatically (on Homebrew, add --without-stockfish to skip it); when running the raw binary you can install it separately with brew install stockfish. Stockfish does not need to be present for the other engines.

Engine	ELO	Description
noise (default)	750–1250	Material + center + mobility + configurable noise
adam	~1600	Minimax search + piece-square positional tables
greedy	~500	Always captures highest-value piece
stockfish	1350–2800	Stockfish via UCI subprocess, Elo-limited by -d

Scripts

All commands live in ./scripts/chess.sh:

./scripts/chess.sh play       # build if needed, then run (JVM)
./scripts/chess.sh build      # build JVM distribution only
./scripts/chess.sh test       # run all tests
./scripts/chess.sh native     # build native binary (GraalVM)
./scripts/chess.sh nrun       # build native if needed, then run
./scripts/chess.sh ci         # test + native build

Native Build

Produces a dependency-free binary. Requires GraalVM — set GRAALVM_HOME or the script defaults to:

/Library/Java/JavaVirtualMachines/graalvm-25.jdk/Contents/Home

GRAALVM_HOME=/path/to/graalvm ./scripts/chess.sh native
./build/native/nativeCompile/console-chess

Project Structure

src/main/java/chess/
├── ChessApp.java              # Entry point
├── engine/
│   ├── Color.java             # OUTLINE / FILLED
│   ├── Piece.java / PieceType.java
│   ├── Square.java / Move.java
│   ├── Board.java             # 8×8 grid + move execution
│   ├── MoveGenerator.java     # Legal move generation + check detection
│   ├── Fen.java               # Position → FEN serialization
│   └── GameState.java         # Turn management + game status
├── ai/
│   ├── ChessEngine.java      # Interface: name() + selectMove()
│   ├── NoiseEngine.java      # ELO 750-1250 (default)
│   ├── AdamEngine.java       # ELO ~1600, minimax + piece-square tables
│   ├── GreedyEngine.java     # ELO ~500, captures everything
│   ├── StockfishEngine.java  # Stockfish via UCI subprocess (UciChannel)
│   ├── UciChannel.java       # stdio abstraction for UCI engines
│   └── SubprocessUciChannel.java  # ProcessBuilder-backed UciChannel
└── tui/
    ├── ChessModel.java        # tui4j Model: board, cursor, piece selection
    └── virtual/
        ├── VirtualTerminal.java  # Captures rendered output for testing
        └── GamePrinter.java      # Renders GameState to VirtualTerminal

Tech Stack

• Java 21 + Gradle 8.14 (native image built with GraalVM 25)
• tui4j — terminal UI (Elm Architecture)
• JUnit 5 + AssertJ — unit tests
• ApprovalTests — snapshot testing
• GraalVM — optional native binary

Acknowledgements

AdamEngine is a Java port of the evaluation and search logic from adam-mcdaniel/chess-engine (MIT license). The piece-square positional tables and negamax minimax search are adapted from that project.