iterm2-matrix-rain

A Matrix color theme for iTerm2 plus a soft, animated digital rain drawn behind the terminal text. The rain's tint, tempo and density shift gently with Claude Code events: a prompt submitted, a tool running, Claude waiting for you, a tool failure, a finished turn.

Project page with mock screenshots and instructions: https://dharmaje.github.io/iterm2-matrix-rain/

How it works

iTerm2 does not animate GIF backgrounds. A small daemon renders soft PNG frames with Pillow and swaps each opted-in session's background image through the iTerm2 Python API. Claude Code hooks send a one-line state event over a Unix socket, and the daemon eases the rain to the new palette over about a second.

Camera motion (optional, off by default)

With the camera turned on, the rain draws a gold outline around whatever moves in front of the Mac's camera, such as you, and fades back over about five seconds. The gold is stronger for the first six seconds after you start moving. It is off until you run matrix-rain camera enable, and nothing is recorded or stored. See Camera motion for details.

Requirements

• macOS with iTerm2 3.5 or newer
• Python 3.10 or newer (python3)
• iTerm2's Python API turned on: Settings > General > Magic > Enable Python API
• jq is optional; the hook falls back to sed

Install

git clone https://github.com/dharmaje/iterm2-matrix-rain.git
cd iterm2-matrix-rain
./install.sh --install            # .venv, dependencies, Matrix Dynamic Profile
./install.sh --autolaunch         # start the daemon whenever iTerm2 starts
./install.sh --hooks              # prints the Claude Code hook JSON

Before it changes anything, --install (and --autolaunch) checks the dependencies and prints a table such as:

Dependency             Required     Found          Status
macOS                  any          26.1           OK
iTerm2                 3.5+         3.7.6          OK
python3                3.10+        3.12.4         OK
osacompile             any          yes            OK
osascript              any          yes            OK
iTerm2 Python API      enabled      enabled        OK
jq (optional)          any          jq-1.7.1       OK

A missing or too-old dependency, or the Python API being off, stops the installer with one line saying what to install or turn on; nothing is written. Once .venv exists, it compares the installed Python packages with requirements.txt. Installing a missing package needs no answer, but upgrading one that is already installed shows the from and to versions and asks Upgrade? [y/N]. Answering no stops with nothing changed. Pass --yes to accept the prompts in a non-interactive run.

Then choose the Matrix profile. Either make it the default (Settings > Profiles > Matrix > Other Actions > Set as Default) or open a window with it from the Profiles menu. Only sessions using a profile named Matrix animate.

Starting the daemon

./install.sh --autolaunch compiles scripts/autolaunch.applescript with your clone's path and installs it as ~/Library/Application Support/iTerm2/Scripts/AutoLaunch/iterm2-matrix-rain.scpt. iTerm2 runs the scripts in that folder each time it starts. The script asks iTerm2 for an API cookie and key, then starts the daemon in the background with them, logging to ~/Library/Logs/iterm2-matrix-rain.log. It does nothing when a daemon is already running. Because iTerm2 supplies the cookie itself, there is no "allow this script to connect" question.

To start it now without restarting iTerm2:

osascript ~/Library/Application\ Support/iTerm2/Scripts/AutoLaunch/iterm2-matrix-rain.scpt

The daemon exits when iTerm2 quits, so the next iTerm2 launch starts a fresh one.

A launchd LaunchAgent does not work. A process that iTerm2 did not start has to fetch the cookie through AppleScript, and a launchd job has no Automation permission to do that, so the request never returns. The daemon gives up after 15 seconds and logs why.

To run it by hand instead, from an iTerm2 terminal (iTerm2 may ask once whether to allow the connection):

.venv/bin/matrix-rain daemon

Updates

Each time the daemon starts, before it connects to iTerm2, it:

1. Reads the installed iTerm2 version and logs it next to the version this was built for (iTerm2 3.7). When the installed major.minor is newer, it posts one macOS notification per newer version, suggesting you check for an update if the rain misbehaves. It never stops for a newer version, but it exits on anything older than 3.5.
2. Runs git fetch origin in this clone, with a 20 s limit and no output to the terminal. It fast-forwards to origin's default branch only when the working tree is clean, HEAD is on that branch and no local commits would be lost. Then it reinstalls requirements.txt into .venv, posts a notification naming the new version and restarts itself. A dirty, diverged or offline clone logs one line and starts with the current code.

The check runs at most once an hour. matrix-rain daemon --update-now or matrix-rain update forces it, and matrix-rain version prints the project version, the iTerm2 version it was built for and the installed one. To turn updates off, or only be notified, put this in ~/.config/iterm2-matrix-rain/config.toml:

[update]
auto = false          # skip the update step entirely
# check_only = true   # or: notify that an update exists, change nothing

This is the beginning of the README. Read the rest at the original. Read the full README ↗