Irix on Your Terminal in Ten Minutes#

Irix is a palette, not a theme: five chambers of four hues each, twelve shades per hue, dark and light siblings for every one of them. This tutorial walks the whole loop once — install, look at the palette, paint your terminal with it, wire it into your prompt, glance at the HUD, then flip the whole thing to light — so you have a working mental model before you go reaching for the how-to guides.

Everything below was run from a checkout of this repository. Skim ahead to Install for why that’s the recommended path right now rather than a packaged install.

Install#

git clone <this repository> irix && cd irix
uv sync

Note

A published uv tool install irix exists on PyPI and does work — it currently ships the colorcode console script (matching this doc’s own index page usage note) plus promptcode. It predates this repository’s irix, kittyhud, and themecode scripts, so it can’t carry you through this whole tutorial yet. Until a fresh release ships, run everything here as uv run <script> from a checkout, as below.

From here on, every command is uv run <script> from the repo root. If you’d rather not prefix every call, uv tool install . from the checkout puts irix, colorcode, promptcode, kittyhud, and themecode on your PATH — drop the uv run prefix in that case. irix generate/irix check still want to run from inside a checkout either way (they write into/diff against the repo’s own out/); irix deploy, colorcode, promptcode, and kittyhud don’t care where you run them from.

See the palette#

irix targets lists every one of the engine’s 24 registered targets — one row per application it knows how to paint, with the filename(s) each mode renders:

uv run irix targets

alacritty    terminals   dark=terminals/alacritty.toml, light=terminals/alacritty-light.toml
...
kitty        terminals   dark=terminals/kitty.conf, light=terminals/kitty-light.conf
...
swatches     web         dark=web/irix-dark-swatches.svg, light=web/irix-light-swatches.svg
...

For something you can actually look at, generate the swatch sheets — a 20-hue x 12-shade grid, one SVG per mode:

uv run irix generate swatches --out /tmp/irix-palette

Open /tmp/irix-palette/web/irix-dark-swatches.svg (and its -light sibling) in a browser or image viewer. Every hue-shade address you’ll see anchored throughout this tutorial — slate-shape1, cyan-sign1, jade-text1 — is a labeled cell on that sheet.

Deploy a terminal theme#

irix deploy <target> copies a target’s already-generated artifacts from the packaged out/ tree to that application’s real config location. Kitty is the engine’s reference target, so it’s the cleanest first deploy:

uv run irix deploy kitty --dry --verbose

Warning

Run the dry version first and read it. irix deploy kitty writes straight to $XDG_CONFIG_HOME/kitty/kitty.conf — kitty’s primary config filename — with a colors-only file (foreground/background, tab bar, color0-color15, marks). If you already have a kitty.conf with fonts, keybindings, or other settings, a real (non---dry) deploy overwrites it outright; there’s no merge. Back up an existing kitty.conf first, or point XDG_CONFIG_HOME at a scratch directory the way this tutorial does below.

Dropping --dry performs the copy for real (sandboxed here so nothing touches a real home directory):

export XDG_CONFIG_HOME=/tmp/irix-sandbox/.config
uv run irix deploy kitty --verbose

copied .../out/terminals/kitty.conf -> /tmp/irix-sandbox/.config/kitty/kitty.conf
copied .../out/terminals/kitty-light.conf -> /tmp/irix-sandbox/.config/kitty/kitty-light.conf

Two files land side by side: kitty.conf (the one kitty actually reads) and kitty-light.conf (the light sibling, deployed alongside it but not auto-selected — kitty itself has no dark/light switch). See Switch to light below for what to do with that second file, and How to Deploy Each Target for the full per-application rundown — including the ghostty and alacritty variants, which follow the same shape (ghostty even renames the files into kitty’s themes/ convention: themes/irix-dark, themes/irix-light, no extension).

Wire colorcode and promptcode into a zsh prompt#

colorcode sets the terminal background by directory/command trigger; promptcode renders a compressed, colored path segment for the prompt line itself. Both are meant to be called from a zsh precmd hook, once per prompt.

A minimal wiring, verified end to end in a real zsh session:

# ~/.zshrc
autoload -Uz add-zsh-hook

_irix_precmd() {
  local exit_status=$?  # capture first -- anything else here clobbers $?
  colorcode -d "$PWD" -n "${history[$HISTCMD]:-}" -s "$exit_status" 2>/dev/null &!
  PROMPT="$(promptcode --fmt zsh) %# "
}
add-zsh-hook precmd _irix_precmd

A few things worth knowing about that snippet:

  • colorcode is backgrounded and disowned (&!) so a slow trigger lookup never stalls your prompt; it talks to the terminal directly via an OSC 11 escape, so it doesn’t need to hand anything back to the shell.

  • ${history[$HISTCMD]:-} passes the whole last command line, not just the command word — fine, because colorcode’s command triggers are prefix-matched regexes (^git still matches git commit -m wip).

  • promptcode --fmt zsh emits real zsh prompt-expansion syntax (%F{#RRGGBB}...%f) as a plain string. Because the string is built and assigned to PROMPT directly inside the hook function — not embedded as $SOME_VAR inside a PROMPT='...' literal — this works with or without setopt PROMPT_SUBST.

With no trigger config at all, colorcode -c slate still works as an explicit, no-surprises demo:

uv run colorcode -c slate -v

Applying color: 'slate' -> '#18191B'

Trigger configs (directory/command rules) are covered in How to Deploy Each Target; the shell section there also has the fzf/lsd/starship/delta/btop companions that round out a terminal built on the same palette.

See the HUD#

kittyhud paints a small five-cell bar — one cell per Irix chamber — in the corner of a Kitty window, highlighting whichever chamber your current directory’s index digit belongs to (_2_documents lights the third cell, and so on):

uv run kittyhud
uv run kittyhud --clear   # remove just this HUD

Note

kittyhud is Kitty-only in effect, not by refusal: it always writes Kitty’s graphics-protocol escape codes, with no check for whether you’re actually inside Kitty. Inside Kitty you get the HUD; in any other terminal the bytes are silently ignored (verified: running it in a plain terminal produces no visible output and no error). --clear is always safe to run.

Switch to light#

Every one of the 24 targets renders both modes, and colorcode/promptcode/kittyhud all resolve which one to use through the same precedence: an explicit --mode flag wins, then $IRIX_MODE, then dark.

IRIX_MODE=light uv run promptcode --path . --fmt plain
uv run promptcode --path . --fmt ansi --mode dark    # explicit --mode wins over $IRIX_MODE

Set it once for a whole session and every one of those tools follows:

export IRIX_MODE=light
uv run colorcode -c slate -v

Applying color: 'slate' -> '#F9F9FB'

(compare that against dark slate’s #18191B from earlier — same address, the palette’s other half.)

irix generate/irix check/irix deploy take their own --mode {dark,light,both} flag instead — it’s a build-time artifact selector, independent of $IRIX_MODE, and defaults to both. That’s why kitty-light.conf was already sitting next to kitty.conf after the plain irix deploy kitty above: both modes deploy together unless you narrow it.

Getting each individual application (vim, sublime, vscode, the browser userstyles, …) to actually pick up its light sibling — since most of them, kitty included, have no built-in dark/light switch of their own — is the whole subject of How to Switch Between Dark and Light.

Where to go next#