PuzzleTea is a terminal-based puzzle game collection built with Bubble Tea. It offers nine distinct puzzle types, including Nonogram, Sudoku, Word Search, and Takuzu, each with multiple difficulty modes. Designed for both casual play and serious challenge, PuzzleTea features daily puzzles generated using deterministic seeding, ensuring the same date produces the same puzzle globally. Players can track streaks, earn XP, and level up across categories, while a stats dashboard provides insights into progress and achievements.
Key Features:
Nine puzzle games: Nonogram, Nurikabe, Sudoku, Shikaku, Word Search, Hashiwokakero, Hitori, Lights Out, and Takuzu.
Daily puzzles with deterministic seeding for consistent generation.
XP progression and leveling system based on victories.
Stats dashboard for tracking profile level, streaks, and category-specific progress.
365 color themes with live preview and WCAG-compliant contrast enforcement.
Mouse support for Nonogram, Nurikabe, Shikaku, Word Search, and Lights Out.
Puzzle persistence via SQLite, allowing users to resume or revisit saved games.
Ideal for puzzle enthusiasts and casual players alike, PuzzleTea challenges users to improve their logic and problem-solving skills while offering a customizable and rewarding experience. It is perfect for those seeking daily entertainment with streak tracking or looking to tackle puzzles in varying difficulty levels. The software can be installed via winget.
README
PuzzleTea
A terminal-based puzzle game collection built with Bubble Tea.
Fifteen puzzle games, multiple difficulty modes, daily and weekly deterministic challenges, XP progression, 365 theme options, and an explicit built-in registry plus metadata catalog for adding new games.
Daily puzzles -- A unique puzzle generated each day using deterministic seeding. Same date, same puzzle for everyone. Streak tracking rewards consecutive daily completions.
Weekly gauntlet -- Each ISO calendar week has a shared 99-puzzle ladder. The current week unlocks sequentially from #01 to #99; past weeks can be reviewed from completed saves only.
XP and leveling -- Per-category levels based on victories. Harder modes yield more XP. Daily puzzles grant 2x XP, and weekly puzzles add slot-based bonus XP.
Stats dashboard -- Profile level, daily streak status, weekly completion progress, victory counts, and XP progress bars per category.
365 color themes -- Live-preview theme picker with WCAG-compliant contrast enforcement. Dark and light themes included.
Mouse support -- Drag interactions in Nonogram, Nurikabe, Shikaku, Spell Puzzle, and Word Search; click-to-focus in Fillomino, Hashiwokakero, Hitori, Sudoku, Sudoku RGB, Takuzu, and Takuzu+; click-to-rotate in Netwalk; click-to-toggle in Lights Out.
Seeded puzzles -- Share a seed string to generate identical puzzles across sessions and machines.
Save/load persistence -- Games auto-save to SQLite. Resume any in-progress game by name.
Download the latest binary for your platform from the Releases page.
From source
Requires Go 1.24+.
go install github.com/FelineStateMachine/puzzletea@latest
Or clone and build:
git clone https://github.com/FelineStateMachine/puzzletea.git
cd puzzletea
just # or: go build -o puzzletea
Usage
Launch the interactive menu:
puzzletea
The Play menu includes:
Create for a new puzzle by category and mode
Continue for saved games
Daily for the shared deterministic daily puzzle
Weekly for the current or historical weekly gauntlet
Seeded for a custom deterministic seed
Weekly gauntlets use the ISO week-year format shown in the menu, for example
Week 10-2026 # 7. The # value is the currently active weekly challenge for
that week. Current-week puzzles unlock one at a time; older weeks are review-only.
Start a new game directly:
puzzletea new nonogram classic
puzzletea new fillomino "Hard 10x10"
puzzletea new ripple-effect "Medium 7x7"
puzzletea new sudoku hard
puzzletea new ripeto expert
puzzletea new spell beginner
puzzletea new lights-out
puzzletea new netwalk "Easy 7x7"
puzzletea new hashi "Easy 7x7"
Mode names are matched case-insensitively after normalizing spaces, hyphens,
and underscores. Multi-word mode titles usually need quotes.
Resume and manage saved games:
puzzletea list # show saved games
puzzletea list --all # include abandoned games
puzzletea continue amber-falcon # resume by name
Use seeds for deterministic puzzle generation:
# Deterministically selects game, mode, and puzzle from one seed.
puzzletea new --set-seed myseed
# Deterministically generates a puzzle within a chosen game/mode.
puzzletea new nonogram epic --with-seed myseed
Export printable puzzle sets to JSONL:
# Stream JSONL to stdout (redirect if desired)
puzzletea new nonogram mini --export 2 > nonogram-mini-set.jsonl
# Single mode export
puzzletea new nonogram mini -e 6 -o nonogram-mini-set.jsonl
# Mixed modes within a category (deterministic with --with-seed)
puzzletea new sudoku --export 10 -o sudoku-mixed.jsonl --with-seed zine-issue-01
--title sets the pack subtitle (title page, and outside cover when enabled), and --volume sets the volume number.
half-letter renders a plain booklet interior with no cover block.
duplex-booklet automatically includes the 4-page black-ink cover block with blank inside covers, and the actual cover color comes from the physical stock you print on.
When duplex-booklet is enabled, the title page shifts to logical page 3 so the first two and last two pages stay on cover stock.
Page count is always auto-padded to a multiple of 4 for booklet printing.
Use --sheet-layout duplex-booklet to emit a landscape US Letter PDF with two portrait half-letter booklet pages per sheet side:
Several shorthand names are accepted for games: polyomino/regions for Fillomino, hashi/bridges for Hashiwokakero, lights for Lights Out, network for Netwalk, islands/sea for Nurikabe, ripple for Ripple Effect, spell/spellpuzzle for Spell Puzzle, rgb sudoku/ripeto/sudoku ripeto for Sudoku RGB, binairo/binary for Takuzu, takuzu plus/binario+/binario plus for Takuzu+, words/wordsearch/ws for Word Search, and rectangles for Shikaku.
Controls
Global
Key
Action
Enter
Select
Escape
Return to the menu or go back
Ctrl+R
Reset puzzle
Ctrl+H
Toggle full help
Ctrl+C
Quit
Navigation
Arrow keys, WASD, and Vim bindings (hjkl) are supported for grid movement across all games.
Mouse
Nonogram, Nurikabe, Shikaku, Spell Puzzle, and Word Search support drag interactions. Fillomino, Hashiwokakero, Hitori, Sudoku, Sudoku RGB, Takuzu, and Takuzu+ support mouse focus or click-to-cycle interactions. Netwalk supports click-to-rotate and right-click lock toggles. Lights Out supports click to toggle. See each game's help for details.
Game Persistence
Games are automatically saved to ~/.puzzletea/history.db (SQLite). Navigating away saves progress; quitting with Ctrl+C marks the game as abandoned. Completed games are preserved and can be revisited.
Daily and current-week weekly puzzles keep a single deterministic save per seed/week slot. Completed weekly puzzles from prior weeks reopen in review mode and are not modified when viewed again.
Previews
Fillomino
Grow numbered regions so each connected region reaches its exact size.
just # build
just run # build and run
just test # run tests (go test ./...)
just test-short # run tests, skipping slow generator tests
just lint # run golangci-lint
just fmt # format with gofumpt
just tidy # go mod tidy
just install # install to $GOPATH/bin
just clean # remove build artifacts
just vhs # generate all VHS GIF previews
Run a single package's tests:
go test ./nonogram/
go test ./sudoku/ -run TestGenerateGrid
All code must pass gofumpt and golangci-lint before committing. CI runs both on every PR.
Adding a New Puzzle
PuzzleTea uses an explicit built-in registry plus a metadata catalog. To add a new puzzle type:
1. Create the game package
Create a directory (e.g., mypuzzle/) with these files:
File
Purpose
gamemode.go
Mode structs embedding game.BaseMode, Modes, ModeDefinitions, package-level Definition, and the built-in Entry
model.go
Model struct implementing game.Gamer
export.go
Save struct, GetSave(), ImportModel() for persistence
keys.go
Game-specific KeyMap struct
style.go
lipgloss styling and rendering helpers
generator.go
Puzzle generation logic (if applicable)
grid.go
Grid type and serialization (for grid-based games)
help.md
Embedded rules/help content wired into the runtime entry
print_adapter.go
Optional printable export adapter for JSONL/PDF support
