8000 GitHub - alexzunega/kenken: Terminal KenKen (Calcudoku) puzzle game — zero dependencies, modern truecolor + classic curses TUIs · GitHub
[go: up one dir, main page]

Skip to content
alexzunegaPublic

About

Terminal KenKen (Calcudoku) puzzle game — zero dependencies, modern truecolor + classic curses TUIs

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

KenKen TUI

A terminal KenKen (a.k.a. Calcudoku) puzzle game, inspired by kenkenpuzzle.com. Pure Python, zero dependencies (standard library only).

  • Board sizes from 4×4 up to 9×9
  • Three difficulty levels — Easy / Medium / Hard
  • A live timer that pauses with the game
  • Every puzzle is procedurally generated with a guaranteed unique solution
  • Pencil marks (notes), undo, mistake highlighting, and instant win detection

Two front-ends ship in the box:

  • a modern front-end (default) that drives terminals like Ghostty, Kitty and WezTerm directly — truecolor, mouse, the Kitty keyboard/graphics protocols, hyperlinks, desktop notifications and more;
  • a portable classic front-end built on the standard-library curses.
┏━━━━━┳━━━━━┯━━━━━┓
┃11+  ┃2÷   │     ┃
┃  4  ┃  6  │  3  ┃
┣━━━━━╇━━━━━┿━━━━━┫
┃20×  │     ┃3-   ┃
┃  5  │  4  ┃  1  ┃
┣━━━━━┿━━━━━╉━━━━━┫
┃     │     ┃     ┃
┃  3  │  1  ┃  ...┃
┗━━━━━┷━━━━━┻━━━━━┛

Install

KenKen runs on macOS and Linux.

Standalone binary (no Python needed)

One line — detects your platform, downloads the latest release binary and installs it to ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/alexzunega/kenken/main/install.sh | sh

Then just run:

kenken

Prefer to do it by hand? Grab the .tar.gz for your platform from the latest release, untar it, and put the kenken binary anywhere on your PATH.

With uv or pipx (if you have them)

uvx --from git+https://github.com/alexzunega/kenken kenken   # run without installing
uv tool install git+https://github.com/alexzunega/kenken      # or install the `kenken` command
pipx install git+https://github.com/alexzunega/kenken

From source

Requires Python 3.10+ (uses int.bit_count) — nothing else:

git clone https://github.com/alexzunega/kenken
cd kenken
python3 kenken.py
# or
python3 -m kenken

Running

The modern front-end is used automatically on an interactive terminal. Force a particular one with a flag or the KENKEN_TUI environment variable:

python3 -m kenken --modern     # truecolor / Ghostty front-end
python3 -m kenken --classic    # portable curses front-end
KENKEN_TUI=classic python3 -m kenken

If the modern front-end can't start (e.g. output is not a real terminal) it falls back to the classic one automatically. Set KENKEN_NO_GRAPHICS=1 to skip the Kitty-graphics menu banner.

A terminal at least ~60 columns wide and ~35 rows tall is recommended for the 9×9 board; smaller boards need less.

Modern terminal front-end

The modern front-end (kenken/modern_tui.py) talks to the emulator directly instead of going through curses, so it can use capabilities curses never exposes. Each is detected at startup and degrades silently when absent:

Ghostty / terminal capability How KenKen uses it
24-bit truecolor Per-cage background tints (graph-coloured) + theming
Synchronized output (mode 2026) Every frame is painted atomically — zero flicker
Kitty keyboard protocol Unambiguous Esc; Shift+arrow jumps to an edge
SGR mouse Click a cell, hover-highlight, wheel to change a digit, clickable buttons
Styled/colored underline Mistakes get a red undercurl (SGR 4:3 + 58)
OSC 8 hyperlinks Footer "How to play" / credits links are clickable
OSC 52 clipboard Solving (or pressing y) copies a shareable result
OSC 9 / OSC 777 notifications A desktop notification fires when you solve
OSC 11 background query Picks a light or dark palette to match your terminal
OSC 0/2 window title The tab title tracks size, difficulty and the clock
Focus reporting (mode 1004) Leaving the window auto-pauses the timer
Kitty graphics protocol A gradient banner is drawn on the menu (RGBA / APC)

The capability strip in the top-right of every screen shows what was negotiated (kbd:kitty, mouse:on, color:24-bit, gfx:on, theme:dark).

How to play

Fill the grid so that every row and every column contains each digit 1..N exactly once. Each outlined cage shows a target and an operation; the digits inside the cage must combine (in some order) to produce the target:

Clue Meaning
11+ the cage's digits sum to 11
20× the cage's digits multiply to 20
3− the two digits differ by 3
2÷ the larger digit divided by the smaller is 2
4 a single given cell (already filled in for you)

Controls

Key Action
Arrow keys / hjkl Move the curso 6718 r
Shift+arrow Jump to the edge (modern only)
1–9 Enter a digit (toggles if repeated)
0 / Space / ⌫ Clear the cell
n Toggle notes (pencil-mark) mode
u Undo
p Pause / resume (also pauses timer)
m Toggle mistake highlighting
r Reset the puzzle
y Copy the result to the clipboard (modern only)
N New game (back to menu)
q / Esc Back to menu (quit from the menu)

In the modern front-end you can also click a cell to select it, scroll the wheel over a cell to cycle its digit, and click the footer buttons (Notes, Undo, Pause, …).

Each cage is drawn with a bright, heavy outline against a dim internal grid, and on 256-colour terminals it is also given its own dark background tint (adjacent cages never share one) so the groups are easy to tell apart at a glance. Given cells are shown in cyan; digits that clash in a row/column, or cages that are filled in incorrectly, are highlighted in red (toggle with m).

Project layout

kenken/
  puzzle.py     data structures, validation, live game state
  generator.py  Latin-square + cage generation, difficulty tuning
  solver.py     MRV + forward-checking solver for the uniqueness guarantee
  logic.py      constraint propagation used for the uniqueness guarantee
  ansi.py       pure escape-sequence primitives (truecolor, OSC, box-drawing)
  terminal.py   raw-mode driver: capability detection, input parser, diff screen
  modern_tui.py modern front-end (truecolor / mouse / Kitty protocols / …)
  tui.py        classic curses front-end (menu, board rendering, play loop)
  __main__.py   `python -m kenken` entry point (front-end selection)
tests/          generator / solver / puzzle + parser / SGR / screen tests (pytest)

Tests

python3 -m pytest -q

About

Terminal KenKen (Calcudoku) puzzle game — zero dependencies, modern truecolor + classic curses TUIs

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0