A sleek, terminal-based Sudoku game built with Go. Play Sudoku right in your terminal with a beautiful interface, multiple difficulty levels, and full theme customization.

Features

Multiple Difficulty Levels: Easy, Normal, Hard, and Lunatic modes to challenge players of all skill levels
Daily Puzzles: Get a new puzzle every day to keep your mind sharp
Smart Gameplay: Auto-check for conflicts, timer support, and intuitive controls
Beautiful Themes: Ships with Solarized Light and Dracula themes, plus support for custom themes
Profile System: Track your stats, achievements, and compete on the leaderboard
Persistent Progress: Save and resume your games anytime
Cross-Platform: Works on Linux, macOS, Windows, and FreeBSD

Installation

Pre-built Binaries

Download the latest release for your platform from the dist/ directory:

# Linux (amd64)
./dist/termdoku-linux-amd64

# macOS (Apple Silicon)
./dist/termdoku-darwin-arm64

# Windows
./dist/termdoku-windows-amd64.exe

Build from Source

Make sure you have Go 1.24+ installed:

# Clone the repository
git clone https://gitlab.com/bereckobrian/termdoku.git
cd termdoku

# Build for your current platform
make build

# Or build for all platforms
make build-all

# Install to your system
make install

Usage

Simply run the binary to start the game:

termdoku

Controls

Arrow Keys / hjkl: Navigate the grid
1-9: Enter numbers
Backspace / 0: Clear cell
?: Show help
q: Quit game
m: Return to main menu

Navigate through the main menu to:

Start a new game with your preferred difficulty
Resume saved games
View your profile (stats, achievements, leaderboard)
Access the database of completed puzzles

Configuration

Termdoku stores its configuration in ~/.termdoku/config.yaml. You can customize:

theme: "dark"           # Options: "light", "dark", "auto", or custom theme name
autoCheck: true         # Automatically highlight conflicts
timerEnabled: true      # Show game timer
bindings: {}           # Custom key bindings (optional)

Custom Themes

One of the coolest features of Termdoku is the ability to create your own themes using TOML files.

Creating a Custom Theme

On first run, Termdoku creates an example theme at ~/.termdoku/themes/example.toml
Create a new .toml file in ~/.termdoku/themes/ with your theme name (e.g., mytheme.toml)
Define your color palette:

Name = "mytheme"

[Palette]
Background = "#1a1b26"
Foreground = "#c0caf5"
GridLine = "#414868"
CellBaseBG = ""
CellBaseFG = "#c0caf5"
CellFixedFG = "#565f89"
CellFixedBG = ""
CellSelectedBG = "#283457"
CellSelectedFG = "#7dcfff"
CellDuplicateBG = "#2e2a2d"
CellConflictBG = "#3b2e3a"
Accent = "#7aa2f7"

Update your config to use the theme:

theme: "mytheme"

Color Fields Explained

Background/Foreground: Main terminal colors
GridLine: Color of the Sudoku grid lines
CellBaseBG/FG: Colors for empty cells you can edit
CellFixedBG/FG: Colors for pre-filled cells (the puzzle clues)
CellSelectedBG/FG: Colors for the currently selected cell
CellDuplicateBG: Highlight color when you have duplicate numbers
CellConflictBG: Highlight color for invalid placements
Accent: Accent color used throughout the UI

All colors should be in hex format (e.g., #ff5555). Leave fields empty ("") to use the terminal default.

Data Storage

Termdoku stores all its data in ~/.termdoku/:

~/.termdoku/
├── config.yaml          # Your configuration
├── termdoku.db         # SQLite database (stats, achievements, games)
└── themes/             # Custom theme files
    ├── example.toml
    └── mytheme.toml

Development


# Format code
make fmt

# Run linter
make lint

# Build for all platforms
make build-all

License

MIT License - see LICENSE for details.

Credits

Built with:

Bubble Tea - Terminal UI framework
Lipgloss - Style definitions
SQLite - Database

Enjoy playing Sudoku in your terminal! If you create a cool theme, feel free to share it.