Matrix rain clock for your tmux workspace

A terminal workspace can be practical without feeling sterile. The Matrix rain clock is a small example: a full-screen animation that runs in its own tmux window, paints falling glyphs down each column, then redraws a large digital clock on top. It is useful enough to glance at, cheap enough to leave open, and simple enough to understand in one sitting.

Why put this in tmux?

tmux is already the stable surface for long-running coding sessions. Your editor, build, logs, database shell, and coding agents can live in named windows that survive a laptop sleep or terminal restart. A clock window fits the same model: it is just another process in the workspace, not a desktop widget, browser tab, or separate app to babysit.

The implementation should avoid dependencies. Python 3 is installed on most developer machines, ANSI escape sequences are enough for color, and tmux can bind a key to open the program in a fresh window. That keeps the setup portable for local terminals, SSH boxes, and remote development hosts.

The rendering model

Treat the terminal as a grid. Each column owns a drop head, a speed, and a short trail. On every frame the head moves down, the program samples a character for each visible trail cell, and it prints the whole frame from the top-left corner. A second pass overlays the clock using a five-row block digit map.

digits = {
    "0": ["###", "# #", "# #", "# #", "###"],
    "1": [" ##", "  #", "  #", "  #", " ###"],
    ":": ["   ", " # ", "   ", " # ", "   "],
}

def draw_clock(canvas, text, row, col):
    for offset, char in enumerate(text):
        glyph = digits[char]
        x = col + offset * 4
        for gy, line in enumerate(glyph):
            for gx, cell in enumerate(line):
                if cell != " ":
                    canvas[row + gy][x + gx] = "\033[1;32m▓\033[0m"

The important detail is the overlay order. Rain is background state. The clock is foreground state. If the program draws the clock first, the next rain pass will punch holes through it. Draw rain, then draw the time.

Make terminal cleanup non-negotiable

Full-screen terminal toys should always restore the screen. Hide the cursor when the animation starts, show it again on exit, clear the screen, and handle interruption signals. Nothing makes a terminal feel broken faster than a hidden cursor left behind by a crashed script.

import signal
import sys

def cleanup(*_):
    sys.stdout.write("\033[?25h\033[0m\033[2J\033[H")
    sys.stdout.flush()
    raise SystemExit

signal.signal(signal.SIGINT, cleanup)
signal.signal(signal.SIGTERM, cleanup)
sys.stdout.write("\033[?25l")

Bind it without stealing tmux defaults

tmux already uses lowercase prefix + t for its built-in clock mode. Leave that alone. Use an uppercase binding for the custom clock so muscle memory still works.

# ~/.tmux.conf
bind T new-window -n 'matrix-clock' 'matrix-clock'

That line opens a new window named matrix-clock and runs the script there. Press q, Ctrl-C, or close the tmux window when you are done.

Design constraints that keep it pleasant

Cap the frame rate around 15 to 20 frames per second. Terminal emulators are fast, but a clock does not need game-loop intensity. On resize, rebuild the per-column arrays instead of trying to preserve drop state. The old state no longer matches the screen geometry, and a reset is visually cleaner than clipped trails.

The result is a small, durable workspace flourish. It is also a useful exercise in treating the terminal as a real UI surface: manage state, redraw predictably, clean up after yourself, and respect the shortcuts users already know.