README
¶
twixtui
TwixT in the terminal: play Alex Randolph's connection game against a bot, against someone at the same keyboard, or against someone on another machine, without leaving your shell.
A quick introduction
https://github.com/user-attachments/assets/79156074-db7b-4ff5-8eea-bd15964c176f
An earlier illustrated tour of the menu, a 24×24 board, hints, remote play, standings and four colour schemes. About a minute; not a recording of the current release. The manual describes today's four effort tiers and placement-only advice.
Quick start · Rules · Manual · Changelog · Releases
[!NOTE] One static binary, built without cgo, nothing to install alongside it — so it plays over SSH, in a pane beside your work, or on a machine with no display server.
TwixT is a two-player connection game. The board is a square grid of holes; each turn you place one peg and join your own pegs with links a chess knight's move apart. A link blocks any other link whose line it crosses — including your own — so the game becomes a running argument about which crossings you can afford to give away. One player connects top to bottom, the other left to right. Randolph devised it on paper in Vienna in 1957; 3M put it in a box in 1962. A terminal is a good place for it: the board is a grid of discrete positions joined by short straight lines, which is what a character cell grid is already good at drawing, and nothing here wants a mouse.
Install
macOS and Linux:
go install github.com/BAKocska/twixtui/cmd/twixtui@latest
Go 1.26 or newer. Or take a prebuilt binary — macOS, Linux or Windows, arm64 or x86-64, with
checksums.txt beside it — from the
releases page. On macOS a binary
downloaded through a browser needs its quarantine attribute cleared first;
the manual has that and the checksum command.
Windows: download the x64 or ARM64 ZIP from the releases page, verify and
extract it as described in the manual, then run
.\twixtui.exe in Windows Terminal. Or build this checkout in PowerShell:
go build -o twixtui.exe ./cmd/twixtui
.\twixtui.exe
Keep go.work in the checkout: it pins the Windows input-decoder fix.
Versioned go install ...@version does not use that override; Windows builds
currently require the checkout or a packaged ZIP.
The manual has the terminal to run it in, where it keeps its state, and what the test suite needs.
Quick start
twixtui # the menu, and a name the first time
twixtui play bot --tier intermediate --side vertical # one game against the bot
twixtui play local # two players, one keyboard
twixtui learn # the interactive tutorial
twixtui help # every command, with what it is for
What's in the box
| Play a bot | Four effort tiers: beginner, intermediate, a clock-bounded pro, and max, the largest effort on offer. Hints use max's placement-only search under a two-second guard: advice, not a proof of best play. While the bot thinks, its completed depth is shown and esc makes it play now. |
| Hotseat | Two players, one terminal, alternating turns. |
| Remote play | Direct, through a relay you or your opponent runs, or by correspondence with no live connection at all. |
| Learn it | Seven lessons taught by playing them, and a five-step introduction on first run. |
| Profiles & standings | Local names with no passwords, selectable standings and player histories, and verified links back to saved-game replays. |
| Review a game | A numbered entry list, : to jump to an entry, the winning chain at the final position, ? for a bounded engine reading of the entry on screen, and bookmarks and one-line notes (m, e) kept beside the game. Records, including imported ones, are never changed. |
| Analyse a position | Read-only analysis of a saved game, record or move list, with time/node budgets, explicit score bounds, and text or JSON output. |
| Honest rulesets | std, pp and classic make each historical disagreement an explicit setting; boards from 6×6 to 48×48. |
| Themes & cover art | Four colour schemes, and the 1962 box lid drawn beside the menu in character cells. |
| Shell completion | bash, zsh, fish and powershell, each value carrying its own one-line explanation. |
The tiers are measured rather than assumed: on colour-balanced opening pairs,
intermediate beat beginner 24–0 on each of three board sizes. The protocol,
and how much of an edge pro and max do and do not establish, are in
the manual.
Licence
MIT. See LICENSE.
TwixT was designed by Alex Randolph. This is an independent implementation, not affiliated with, endorsed by, or licensed from any publisher of the board game.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package assets embeds the artwork the interface ships.
|
Package assets embeds the artwork the interface ships. |
|
gen
command
Command gen regenerates the reduced cover artwork in assets/ from a full-resolution source.
|
Command gen regenerates the reduced cover artwork in assets/ from a full-resolution source. |
|
cmd
|
|
|
twixtui
command
Command twixtui plays TwixT in the terminal.
|
Command twixtui plays TwixT in the terminal. |
|
Package docs embeds the project's reference documents so that the command line can print them without needing the repository or a network connection.
|
Package docs embeds the project's reference documents so that the command line can print them without needing the repository or a network connection. |
|
internal
|
|
|
app
Package app is the interactive shell: the screens a player moves between and the state they share.
|
Package app is the interactive shell: the screens a player moves between and the state they share. |
|
bot
Package bot plays TwixT. One alpha-beta search backs four effort tiers and the hint feature; the tiers differ in the guards they search under — how long they may think, how deep they may look, how many nodes they may visit — in how many candidate moves they keep, and in how much of the evaluation they are allowed to see.
|
Package bot plays TwixT. One alpha-beta search backs four effort tiers and the hint feature; the tiers differ in the guards they search under — how long they may think, how deep they may look, how many nodes they may visit — in how many candidate moves they keep, and in how much of the evaluation they are allowed to see. |
|
cli
Package cli builds the command line.
|
Package cli builds the command line. |
|
cover
Package cover draws the artwork behind the menu.
|
Package cover draws the artwork behind the menu. |
|
e2e
Package e2e drives the compiled binary inside a real terminal so that rendering, key handling and resize behaviour can be asserted on the frames a user would actually see.
|
Package e2e drives the compiled binary inside a real terminal so that rendering, key handling and resize behaviour can be asserted on the frames a user would actually see. |
|
gamestore
Package gamestore keeps games on disk: finished games worth replaying, games interrupted part way through, and correspondence games waiting for the opponent's next move code.
|
Package gamestore keeps games on disk: finished games worth replaying, games interrupted part way through, and correspondence games waiting for the opponent's next move code. |
|
humantime
Package humantime renders an instant as the rough age a person would say out loud: "just now", "3 minutes ago", "yesterday".
|
Package humantime renders an instant as the rough age a person would say out loud: "just now", "3 minutes ago", "yesterday". |
|
leaderboard
Package leaderboard records finished games and ranks the players who played them.
|
Package leaderboard records finished games and ranks the players who played them. |
|
learn
Package learn holds the interactive tutorial: an ordered set of lessons, each a sequence of steps that pairs a position on the board with a short piece of prose, and where useful with a task the learner answers by choosing a hole.
|
Package learn holds the interactive tutorial: an ordered set of lessons, each a sequence of steps that pairs a position on the board with a short piece of prose, and where useful with a task the learner answers by choosing a hole. |
|
netplay
Package netplay carries a TwixT game between two machines.
|
Package netplay carries a TwixT game between two machines. |
|
profile
Package profile stores the local player identities twixtui plays under.
|
Package profile stores the local player identities twixtui plays under. |
|
study
Package study keeps a player's own notes and bookmarks on saved games.
|
Package study keeps a player's own notes and bookmarks on saved games. |
|
theme
Package theme holds the colour schemes the board and the interface are drawn with, and remembers which one the player chose.
|
Package theme holds the colour schemes the board and the interface are drawn with, and remembers which one the player chose. |
|
ui
Package ui is the reusable terminal view layer for TwixT: a board renderer with two drawing scales and a scrolling viewport, a layout engine that fits board and information panel into any terminal size, and a data-driven keymap.
|
Package ui is the reusable terminal view layer for TwixT: a board renderer with two drawing scales and a scrolling viewport, a layout engine that fits board and information panel into any terminal size, and a data-driven keymap. |
|
winfs
Package winfs holds the Windows filesystem primitives twixtui's stores need and the standard library does not offer: a whole-file lock, opening a file for reading in a way that does not block its replacement, and replacing a file in place.
|
Package winfs holds the Windows filesystem primitives twixtui's stores need and the standard library does not offer: a whole-file lock, opening a file for reading in a way that does not block its replacement, and replacing a file in place. |
|
winfs/winfstest
Package winfstest makes a directory refuse to be written to, which is what a test needs in order to cover a configuration directory on read-only media or belonging to somebody else.
|
Package winfstest makes a directory refuse to be written to, which is what a test needs in order to cover a configuration directory on read-only media or belonging to somebody else. |