tetrigo: a Go Tetris TUI and reusable game mode packages

Three layers in one repository, aimed at three different goals

The unusual thing about tetrigo is that the README is written for three different readers at once, and the repository is split to serve each of them. The TUI in `cmd/tetrigo/` is for someone who just wants to play Tetris. The packages in `pkg/tetris/modes/` are for someone who wants to build their own Tetris game or user interface without reimplementing the ruleset. The packages in `pkg/tetris/` are for someone who wants to define a new game mode with its own rules and requirements.

That layering is the real product. A Go developer who embeds the mode packages inherits the scoring, the hold behaviour and the game loop without taking the terminal interface, and a developer who goes one level deeper gets the Tetrimino handling, the Matrix and the scoring logic on their own terms. The TUI itself is described as a demonstration of how to use the packages and how to build a TUI with Bubble Tea, which tells you the interface is the entry point, not the destination.

The rules come from a source rather than from taste. The README states that this is a Golang implementation of Tetris following the official 2009 Tetris Design Guideline, and the guideline PDF is kept in `docs/`.

Default controls follow the 2009 guideline, and only the game keys are configurable

The control list is short enough to memorize in one sitting. Move left is `A`, move right is `D`, `S` toggles soft drop on and off, `W` is hard drop, `E` rotates clockwise, `Q` rotates counter-clockwise, `Space` or `Enter` holds the current tetrimino or submits a menu option, `Escape` pauses the game or exits, `Ctrl+C` force quits, and `?` shows the controls help.

The split between configurable and fixed controls is worth knowing. The game controls can be changed in the configuration file. The menu and leaderboard navigation is fixed to the arrow keys for moving, escape to exit and enter to submit, and the README says these are not configurable.

That asymmetry is a small design decision with a practical consequence. If your muscle memory in another terminal game uses a different layout, you can move the game keys, but you cannot remap the menu, so a first session is partly muscle memory and partly fixed convention. The Nix overlay shows the same split from the configuration side, with `keys` able to override `force_quit` and `exit` entries.

Three install routes: release binary, go install, or a Nix flake

The README offers a binary, a source build, and a Nix path, and the three differ in how much you trust the packaging.

The binary route is a download from the releases page on GitHub for your operating system, then running the file. On Linux or macOS the command is `./tetrigo`, and on Windows the binary is `tetrigo.exe`. The README suggests optionally moving the binary into a directory on your `$PATH` so it can be started from anywhere.

The source route uses the standard Go install command, and the version in the README is pinned to an older release than the latest one listed:

go install github.com/Broderick-Westrope/tetrigo/cmd/[email protected]

The minimum Go version comes from `go.mod`, which declares `go 1.23.3`. That mismatch between the version in the install command and the release list is the kind of detail worth noticing before you decide which binary you are running.

The Nix route is a flake, and the README states that the flake installs a wrapper that automatically sets up the database and config in the user's XDG config directory on first run:

nix run github:Broderick-Westrope/tetrigo     # Run the package and delete it
nix build github:Broderick-Westrope/tetrigo   # Build the package into a result symlink
nix shell github:Broderick-Westrope/tetrigo   # Create a temporary shell with the tetrigo binary

The flake also exposes an overlay so tetrigo can be used as a package inside another Nix project, and the package accepts `config` and `dbPath` as override arguments, where `config` mirrors the values in `example.config.toml` and `dbPath` points at a `.db` file.

The CLI can skip the menu and jump straight into Marathon

Running tetrigo with no subcommand or flags opens the game in the menu, where simple settings such as the player name and the game mode can be set by hand. The flag form skips that step and goes straight into a mode, and the README's example starts Marathon at level 5 under a player name:

./tetrigo play marathon --level=5 --name=Brodie

Argument parsing is handled by the Kong library, which the dependency list shows as `github.com/alecthomas/kong v1.4.0`. The remaining options are discoverable through the help output:

./tetrigo --help

Two other flags cover the file locations that a headless or scripted setup usually needs to change. The config file can be pointed at an explicit path with `--config`, and the database path with `--db`:

./tetrigo --config=/path/to/config.toml
./tetrigo --db=/path/to/data.db

That combination is what makes the game usable in a container or a wrapper script, where the default XDG locations may not exist or may not be writable.

Config and data live in XDG directories, and the README is specific about where

Defaults are sensible enough that configuration is optional, and the README says that if no config file is found, sensible defaults are used.

The config file is looked up at `./tetrigo/config.toml` inside the device's XDG config directory. The XDG behaviour comes from the adrg/xdg library, which defines `XDG_CONFIG_HOME` per operating system, and the README walks through the macOS case where the directory is `~/Library/Application Support` if it exists and `~/Library/Preferences` otherwise. An example configuration file ships in the repository as `example.config.toml`.

The game data goes into a SQLite database, using the go-sqlite3 driver, stored by default at `./tetrigo/tetrigo.db` within the XDG data directory, with the macOS equivalent again being `~/Library/Application Support` or `/Library/Application Support`. Both locations use the `./tetrigo/` subdirectory, which is a convention worth knowing when you go looking for a file that is not where you expected it.

The database is what makes the leaderboard persistent rather than per-session, since the menu exposes a leaderboard alongside the game modes. The README does not describe the schema, so anyone who wants to query or migrate that data directly is working without documentation for it.

Build tooling: Task, GoReleaser and a scratch-based Dockerfile

Development tasks run through Task, and the configuration lives in `Taskfile.yaml`. Once the Task CLI is installed, the list of available tasks comes from:

task -l

The repository also carries `.goreleaser.yaml` for build and release automation, `.golangci.yaml` for linting, and `.mockery.yaml` for mock generation, which tells you the project expects generated test doubles rather than hand-written ones. The dependency list includes `github.com/stretchr/testify v1.9.0` and a TeaStream based testing package, `github.com/Broderick-Westrope/x/exp/teatest`, so the terminal interface has its own test harness.

The Dockerfile is unusually minimal, starting `FROM scratch` and copying a single binary into `/usr/local/bin/tetrigo`. It declares a `VOLUME /data`, exposes `53531/tcp`, and sets the entrypoint to the binary. A scratch base image is the right call for a static Go binary, since it removes the shell and package manager from the image entirely.

The exposed port is the unexplained part. The README never mentions networking, and a terminal Tetris client has no obvious reason to listen on a TCP port. The `internal/` and `scripts/` directories exist at the top level, and the README does not describe their contents, so the port's purpose cannot be traced to anything the documentation states.

What tetrigo is not, and how it differs from a single-file Tetris clone

The obvious alternative is a self-contained Tetris program, one file that draws a board and handles keys, which is what most people build as a first Go exercise. The difference in approach is packaging rather than gameplay.

A single-file clone mixes rules, rendering and input handling together, so the rules are unavailable to anyone who wants a different interface. tetrigo separates them into `pkg/tetris/` for the core logic including the tetriminos, the Matrix and the scoring, and `pkg/tetris/modes/` for the game modes built on top. If your goal is a web client, a mobile client or a replay viewer, the mode packages are usable on their own, and the terminal interface is one consumer of them rather than a dependency of them.

The other difference is persistence and configuration. A clone typically keeps a high score in memory for the session. tetrigo writes to a SQLite database in the XDG data directory, so scores survive across runs, and it accepts TOML configuration for keys and game settings, which a clone rarely bothers with.

Against that, tetrigo brings a real constraint: it is a GPL-3.0 project, and the repository is not archived, but the last push was on 2026-04-05 and the listed releases date from 2024-12-27. A fork that wants a new upstream dependency is taking on that. The README also points to a beginners guide for how to play Tetris, which is a nod to the fact that the implementation, not the tutorial, is the interesting part.

Editorial conclusion

Use tetrigo if you want a keyboard Tetris in the terminal with a persisted leaderboard, or if you are a Go developer who needs Tetris rules or a game mode packaged separately from any UI. Do not reach for it if you want a graphical client, a Windows-native build you did not compile yourself, or a project with an active upstream. Verify first that the version you install matches your expectations, because the README's own install command pins v0.1.6 while the releases page lists v0.2.0, and the last push was on 2026-04-05.

Frequently asked questions

Official sources

1. Broderick-Westrope/tetrigo on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases