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 ┃ ...┃
┗━━━━━┷━━━━━┻━━━━━┛
KenKen runs on macOS and Linux.
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 | shThen just run:
kenkenPrefer 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.
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/kenkenRequires Python 3.10+ (uses int.bit_count) — nothing else:
git clone https://github.com/alexzunega/kenken
cd kenken
python3 kenken.py
# or
python3 -m kenkenThe 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 kenkenIf 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.
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).
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) |
| 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).
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)
python3 -m pytest -q