gambit

README

gambit

n. an opening that sacrifices material for position. Also: two bots arguing in algebraic notation.

Two chess agents play each other, every move logged to the terminal in algebraic notation — headless by default, or in an optional Ebiten window. Built as a testbed for experimenting with search strategies — see docs/demos.md.

Install

Homebrew

brew install danielriddell21/tap/gambit         # CLI (all platforms)
brew install --cask danielriddell21/tap/gambit  # native macOS GUI window

Layout

• cmd/gambit — entry point.
• pkg/chess — reusable chess engine (board, moves, legality, FEN, results). The only public package.
• internal/agent — pluggable Agent interface + the random and minimax strategies.
• internal/game — turn orchestration, draw detection, SAN.
• internal/gui — Ebiten window + the Run/Available seam (headless fallback without the ebiten tag).

Quick start

Needs Go 1.26.3, just, and (for the GUI) Ebiten's system deps.

just run                       # terminal: minimax (white) vs random (black)
just gui                       # Ebiten window (opt-in, -tags ebiten)
just test                      # tests        just perft   # move-gen correctness
just lint                      # golangci-lint just demos   # regenerate demo GIFs

Flags: --white, --black, --depth, --seed, --fen, --delay.

Play against an agent yourself: set a side to human in the GUI build and click a piece then a destination.

just gui -- --white human --black minimax   # you (white) vs minimax

Linux: OpenGL/X11 libraries

The window needs OpenGL/X11. On Debian/Ubuntu:

sudo apt install libgl1-mesa-dev libxrandr-dev libxcursor-dev libxinerama-dev libxi-dev

Adding a strategy

Implement agent.Agent and agent.Register it in an init — the game loop and GUI need no changes. Board.MakeMove/UnmakeMove (for alpha-beta) and Board.ApplyMove (clone, for keeping many positions alive) are both available, and the headless build batches games with no display.

Documentation

• Demos