TETRIS BREAK

A polished, guideline-style GUI Tetris for Windows that pops up while Claude Code compacts context — so you have something to do during the wait. It also runs as a normal game you can launch any time, with a floating side launcher and a global hotkey.

Pure Python + Tkinter (standard library) — no pip installs required.

Features

• Modern Tetris feel — SRS rotation with wall kicks, hold / save piece, ghost piece, 7-bag randomizer, NEXT × 5 preview, soft drop, hard drop.
• Lock delay with move-reset — you can still slide / rotate a piece after it lands.
• DAS / ARR auto-shift, level-based gravity, scoring with combo / back-to-back / T-spin.
• High-score persistence, ESC pause, click-to-resume 3-2-1 countdown.
• 4 themes (Neon / Midnight / Sakura / Mono), switch in-game with T.
• One-click global hotkey Ctrl+Alt+T — run install.bat once; it summons the game from anywhere, works immediately and auto-starts each login. Plus an optional click-chip.
• Tuned to be lag-friendly (gentle soft drop, generous lock delay) — comfortable over Remote Desktop / VPN.

Requirements

• Windows
• Python 3.x with Tkinter (the standard Windows python.org installer includes it). Verify: python -c "import tkinter; print(tkinter.TkVersion)"

Quick start

Clone / download, then:

• Play now: double-click tetris-break.bat (or run python tetris.py).
• Hotkey (recommended) — one click: double-click install.bat once. Now press Ctrl+Alt+T anywhere to summon the game (opens it, or brings it to the front if already running). It works immediately and starts automatically on every login. Remove anytime with uninstall.bat. (A tiny hidden helper, hotkey.pyw, runs in the background to listen for the key — no window, no taskbar entry.)
• Floating launcher chip (optional): double-click launcher.bat — a small chip docks to the right edge; click it to open / bring up the game. Drag to move; right-click → Exit.

Pop up automatically during Claude Code compaction

python install_hook.py            # 3-minute break window (default)
python install_hook.py --minutes 5
python install_hook.py --uninstall

This merges a PreCompact hook into your ~/.claude/settings.json (existing settings are preserved; a .bak backup is written). From then on the game appears whenever Claude Code compacts context, and auto-closes when the break window elapses (or press Q).

Start the launcher on login (optional)

• Enable: double-click autostart-on.bat (adds a Startup shortcut + starts it now).
• Disable: double-click autostart-off.bat.

Controls

Key	Action	Key	Action
← →	move	Space	hard drop
↓	soft drop	C / Shift	hold
↑ / X	rotate CW	Esc / P	pause
Z / Ctrl	rotate CCW	T	cycle theme
Q	quit	R	restart (on game over)

When the window loses focus it auto-pauses; click it (or Alt-Tab back / press Ctrl+Alt+T) to resume with a 3-2-1 countdown.

Tuning

Feel is controlled by a few constants near the top of tetris.py:

Constant	Default	Meaning
SOFT_DROP_INTERVAL	0.12	seconds per cell while holding ↓ (bigger = slower)
LOCK_DELAY	0.85	seconds grounded before locking
MAX_RESETS	18	move/rotate resets allowed before a forced lock
DAS / ARR	0.14 / 0.03	auto-shift delay / repeat

The global hotkey is Ctrl+Alt+T, registered by the tiny background daemon hotkey.pyw (change VK_T / the modifiers there for a different combo).

Files

File	Purpose
tetris.py	the game (pure Engine logic + Tkinter app, layered renderer)
hotkey.pyw	invisible background daemon that registers the Ctrl+Alt+T hotkey
install.bat / install.ps1	one click: start the hotkey now + auto-start it each login
uninstall.bat	remove the hotkey
launcher.pyw / launcher.bat	optional floating chip + bring-to-front
tetris-break.bat	launches the game (used by the Claude Code hook)
install_hook.py	install / uninstall the PreCompact hook
autostart-on/off.bat, start-launcher.vbs	login autostart for the chip

Notes

• Windows-only (uses pythonw, the Win32 hotkey API, and Tkinter).
• Single-instance: a second game window, launcher, or hotkey daemon exits immediately (localhost socket guard — game 50574, launcher 50573, hotkey daemon 50575).
• Run the engine self-test with python tetris.py --selftest.

🤖 Built with Claude Code.